1. Introduction

PDPP is an authorization and disclosure protocol for personal data. It defines how a user authorizes an application to access specific data from a data source that holds their records, and how a resource server enforces that authorization.

The protocol specifies:

• A record model for representing personal data as flat relational streams
• A selection request format, the structured request for consent a client submits during authorization (RFC 9396 envelope)
• A grant object representing user-approved, parameterized consent
• A source declaration describing the consent, record, selection, and query surface exposed by either a connector-backed or provider-native source
• A resource server interface for serving records under grant enforcement

Most source platforms do not yet expose a PDPP interface natively. Collection is the bridge for those sources: it brings their data into a resource server so the protocol's consent and enforcement layers can govern access to it. The informative PDPP Collection Profile describes that bridge as builder guidance; it is not a conformance requirement. A connector conforms to PDPP by producing a source declaration valid under Section 5 and serving its data through a resource server conforming to Section 8. No particular collection method is required. The core protocol is useful without it: a resource server holding pre-collected data can serve that data under grant enforcement with no collection machinery involved, and data may also reach it via regulatory data exports, manual import, or platform-native APIs. The consent and enforcement layers defined in this specification (Sections 5-8) are agnostic to the collection method.

Any implementation satisfying the role conformance criteria in Section 9 is PDPP-compliant. This specification does not depend on any specific network, token, ledger, infrastructure provider, hosted service, centralized registry lookup, or deployment of this repository. URI identifiers name sources, purposes, clients, and resources; they do not make the example registries in this document runtime dependencies. Consent integrity comes from the resolved grant and the exact source declaration snapshot retained by the authorization server.

Interoperable core sections

Sections 4-8 define the protocol surfaces that implementations evaluate independently.

Relationship to existing standards

Why a profile rather than a new authorization framework

PDPP is a data-portability profile, not a general authorization framework. It binds to OAuth 2.0 and RFC 9396 for v0.1 because that is what is deployed. On top of that binding it adds what neither UMA nor GNAP defines: a portable record model, purpose-bound durable grants, a declared collection and source layer, and a query surface with grant enforcement. UMA is prior art for the user-managed standing access model. A GNAP binding remains possible. The table above records both. Such a binding remains possible later without changing the record model, the grant, or the resource server interface, because none of those depend on the authorization protocol that produced the grant.

Relationship to sector-specific consent regimes

Note (non-normative). PDPP is a floor, not a ceiling. A source already operating under a stricter or more specific consent regime — open banking, or a health regime built on FHIR — does not lose or weaken any obligation of that regime by also being reachable through PDPP. Where the two differ, the stricter requirement governs that source. Nothing in this specification authorizes a disclosure that the source's own regime forbids, and a PDPP grant is not a substitute for a consent that regime requires. This is a scoping statement rather than a conformance criterion: PDPP defines no test for which of two regimes is stricter, and conformance to this specification is assessed against this specification alone. Compatibility profiles that map a sector regime's consent vocabulary onto PDPP's are a possible future addition and are not defined in v0.1.

2. Terminology and Actors

Actors

The owner is the subject whose records the source holds. Typically this is a person; the protocol itself is subject-neutral, and an organization that authenticates as the account holder participates identically. For grant approval, the authorization server authenticates the subject or each authorized representative. A grant's subject identifies whose data it covers. Approval is attributed to the subject unless the grant records approval by a representative.

Protocol roles

These roles may be co-located in a single deployment (e.g., a personal server acting as both authorization server and resource server) or separated. The spec defines the interfaces between roles, not the deployment topology.

The PDPP Collection Profile defines a third role:

In many deployments, a single personal server fills all three roles. The spec uses "personal server" when referring to a combined deployment, and the specific role name when the distinction matters.

Token resolution: When the AS and RS are deployed separately, the AS-to-RS token-resolution contract is normative: the RS MUST authenticate to the RFC 7662 introspection endpoint and resolve the complete grant enforcement context from its response. The RS MUST enforce the request from that response and MUST NOT make a second AS lookup. For co-located deployments, a local equivalent (shared database or function call) is acceptable. Self-contained JWTs may be used as an optimization but MUST NOT be the sole revocation mechanism (see Section 10).

Trust registry queries

Core refers to a trust registry as a source of requester identity metadata and a positive trust signal at consent, as an external mechanism supporting retention accountability, and as a deferred concern. Core relies on two abstract queries: whether a client identifier is recognized and authorized, and whether a source declaration authority is accepted. Neither query is a wire protocol; an authorization server MAY answer locally or through a remote service.

A registry answer is an assertion that local authorization-server policy evaluates; it is not itself a decision. A conveyed answer identifies six things. It names the subject it concerns and the role, action, or scope the status qualifies. It carries the status itself, the governance framework under which the named issuer conferred it by URI, and the issuer or trust-anchor identifier. It bounds the answer with a validity window, as valid_from and valid_until. Without the subject and the issuer, an answer cannot be attributed or replayed against the right party; without the role or scope, a status does not say what the subject is authorized to do.

An authorization server records the trust signal it relied on — subject, role or scope, status, governance-framework URI, issuer or trust-anchor identifier, valid_from, valid_until, and the time of lookup — on its acceptance record or resulting grant. The lookup time matters because a status may be withdrawn later, and the record has to show what was true when the server relied on it.

Core does not define the registry, transport, recognition mechanism, or withdrawal propagation. A server that consults no registry remains conformant because registry answers inform local policy and never replace the owner’s grant. ToIP’s Trust Registry Query Protocol is an intended future profile binding, not a Core requirement.

Data concepts

Requirements Language

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [RFC 2119] [RFC 8174] when, and only when, they appear in all capitals, as shown here.

This document is normative except where content is explicitly marked as an example, a note, or otherwise non-normative.

This is the only normative document for PDPP Core v0.1 conformance. A profile imposes no requirement on an implementation that does not claim it. A future profile may define a separate named conformance claim only if its own status says so. Core can make support for a Core-defined value depend on such a claim: an implementation that supports a processing permission MUST conform to the permission's defining profile (Section 6). The PDPP Collection Profile and PDPP Source Declaration Discovery and Trust are informative and define no conformance requirements of their own.

3. System Architecture

Every PDPP deployment shares the same authorization core: a user grants a client consent, and the authorization server issues a grant. The resource server that then serves records under that grant is not shown here; how it is populated and operated is deployment-specific (see below).

What differs between deployments is how the resource server that fulfills the grant is populated and operated. This is not a closed set: a resource server may hold pre-collected data with no collection machinery involved, or receive data via regulatory export, manual import, or platform-native APIs (Section 1). The two examples below illustrate the ends of that spectrum; the PDPP Collection Profile is one fulfillment mechanism, not the only one.

Example A: source-native fulfillment. The data source operates its own authorization and resource servers directly; there is no separate collection step.

Example B: personal-server fulfillment. A connector runtime, governed by the Collection Profile, collects data from the source and syncs it into a resource server the user controls.

Core defines no ingest path. Core specifies the authorization server, the resource server, and what passes between them and a client. It does not specify how records reach the resource server, and conformance to Core does not depend on any particular answer. Examples A and B are illustrations, not a classification: a resource server holding data placed there by regulatory export, manual import, a provider's own write path, or a mechanism not yet described is equally within Core. The PDPP Collection Profile describes one such mechanism, connector collection, and describes it for builders rather than as a conformance requirement.

On-behalf-of access is two ordinary grants, not one delegated grant. At the upstream platform, the owner authorizes the personal server to read the owner's data. At the personal server, the owner separately authorizes a downstream client to read owner-held data. These are independent grants, each issued and revocable by the owner. A personal server MAY disclose owner-held data under the fresh downstream grant; it does not pass the platform grant or a downstream PDPP token to the other relationship.

PDPP therefore defines no delegated-grant, sub-grant, or grant-chaining construct, and none is needed to build this. The same shape is already how account aggregation works in deployed systems: an open banking aggregator holds the user’s consent at each bank and its own consent from the user, rather than subdividing one authorization. Where a binding needs to exchange one credential for another across the two relationships, OAuth Token Exchange (RFC 8693) is the existing mechanism, and it is a concern of the binding rather than of Core.

Only live passthrough is bounded by the upstream grant: when the personal server does not hold a copy and reads from the platform to fulfill a downstream request, it MUST stay within the upstream grant. This limit does not constrain a fresh grant for owner-held data. A downstream PDPP token is never forwarded upstream.

Onward transfer is prohibited. A recipient MUST NOT transfer its token or let an ungranted party exercise it.

A different topology — the owner running their own authorization server in front of a platform’s data, so that the platform holds the data but the owner’s server decides who may read it — is not introduced by this specification. It is the arrangement UMA describes, it is not the arrangement above, and it is recorded as deferred rather than left ambiguous.

Protocol layering

PDPP separates three concerns that other systems conflate:

1. Authorization: the user's consent about what is disclosed, to whom, and under what constraints. This is the grant. It is the portable core of PDPP.

2. Disclosure: the records the resource server returns given a valid grant. This is the resource server query API.

3. Collection: how data gets into the resource server in the first place. This is the Collection Profile. It is one answer to this question; pre-loaded data, manual imports, and other mechanisms are equally valid.

The grant and query API are the normative core. Collection is a companion mechanism.

Ingest and sync-state are Collection Profile concerns. The core protocol defines the query API (disclosure) and grant semantics. The Collection Profile defines record ingest and sync-state management endpoints for implementations that claim Collection Profile support.

4. Record Model

Personal data is represented as flat relational streams. This enables streaming, pagination, incremental sync, and compatibility with DTI canonical data models.

Streams

A stream is a named collection of records with a consistent schema. Examples: playlists, messages, sleep_sessions. A stream's shape (its fields and schema) is declared in the source declaration; see Section 5: Source Declaration.

Stream semantics

Each stream has one of two semantic types:

Approximately 95% of personal data by volume is append_only. The remaining 5% is mutable_state. Mutable state records (profiles, preferences, relationships) are often the highest-value context for AI agents.

An authorization server MUST reject a declaration containing an unrecognized streams[].semantics value. A resource server MUST NOT interpret an unrecognized stream semantic as append_only or mutable_state. A later version can add semantic types; an implementation that predates one does not apply the wrong write and sync behavior to it.

Full records and disclosed projections

A stream schema describes a full record before disclosure projection. Every resolved field set includes the stream's schema-required fields (see the note on fields in Section 6). They are the per-stream consent floor, so a disclosed record always carries them.

The RS MUST construct disclosed data from only the top-level members permitted by the grant and the request-time field selection. Missing authorized optional members remain absent. The RS MUST NOT insert nulls or fabricated values for withheld members. A client MUST NOT validate a projected data object as though it were the full stream record.

Envelope identifiers remain part of the record contract. The AS MUST disclose this fact during owner review. Withholding an identifier from data does not hide a matching identifier in the envelope. If envelope disclosure is unacceptable, the AS MUST omit an optional stream or refuse issuance for a required stream.

An RS unable to serve a requested projection without changing the meaning of the disclosed data MUST refuse that read with HTTP 403 disclosure_unavailable. It MUST NOT repair the projection by disclosing unauthorized fields.

Incremental sync

Every stream supports incremental sync. The resource server maintains internal change history for it: the order in which it ingested and changed records, version history for mutable_state streams, and enough deletion information to emit tombstones. This is an implementation detail: the protocol surface is a standard cursor-based query that returns the changes since a given token (see Section 8). The change history is not exposed as a separate stream.

A changes_since token is a position in the resource server's ingestion and change order, not a cursor_field value. A next_changes_since token MUST NOT reveal a readable position or time. Token equality or ordering MUST NOT signal a change that is not visible to the grant, or to the owner session's effective scope, including after a session that returns nothing. One way to meet this is to make each issued token distinct and opaque, for example by encrypting it with fresh randomness. A page cursor MUST NOT reveal a readable position, time, or field value either. An append_only record that arrives late with an earlier cursor_field value, such as a play from yesterday ingested today, therefore appears in the next session.

A client that has previously synced a stream queries for changes by passing its last next_changes_since token. The resource server returns every record not visible at h0 and visible at h1, within the client's grant-authorized field projection. For a record visible at both horizons, it returns the record only if its grant-authorized projection changed.

This design ensures that a client authorized for fields A and B cannot infer that field C changed, even if C was modified after the client’s last sync. The response is a function of the grant, not of the full record state.

This promise covers field values, not membership. Under a time-bounded or resource-filtered grant, the client can see which records are visible. A change to a hidden time field can move a record into or out of that set. Repeated full listings reveal the same change, so no grant of this kind can hide it.

Snapshot model: changes_since returns the full current state of every record not visible at h0 and visible at h1, and of every record visible at both whose grant-authorized projection changed, plus tombstones. It does not return field-level diffs. The client receives a complete record object for any record that changed.

Visibility: A record is visible at a horizon if it exists at that horizon and passes every restriction of the query context at that horizon. For a client token, these are the grant's stream, instance_ids, resources, and time_constraint. For an owner token, they are the owner scope and any request filter. Within a stream, a record is identified by its instance and its canonical key (see RECORD envelope, Record identity below). A changes_since session from horizon h0 to horizon h1 returns:

The session compares only the two horizons. The resource server MUST emit a tombstone for each record visible at h0 and not visible at h1. It MUST NOT emit a tombstone for any other record. This includes a record that was never visible under the query context and a record that was visible only between h0 and h1.

Visibility at h0 uses the record's version at h0. For a deleted record, the h0 version establishes visibility at h0, and deletion evidence establishes only the fact and time of the deletion; the data of the delete directive is never used. The resource server MUST retain the state needed to determine visibility at every unexpired horizon. If it cannot determine that state, it MUST fail the session with 410 cursor_expired.

Sync guarantee: With these rules, two conforming resource servers that hold the same records produce the same synced copy. The guarantee covers only a copy that starts at beginning and is updated by later changes_since sessions. A client that also keeps records from other reads, such as a get by ID between sessions, reconciles them itself; a get by ID returns 404 once the record is not visible. A client MUST treat a tombstone for a record it does not hold as a no-op.

Starting a sync: A client starts incremental sync with changes_since=beginning. beginning stands for an empty horizon at which no record is visible, so the first session returns every visible record and no tombstones. It is not a retained snapshot: it never expires, and it is bound to a grant and query context only when a request uses it. After a completed changes_since=beginning session, the client MUST replace its copy of the stream with that session's result. This applies to every restart, not only a restart after cursor_expired.

Cursor expiry: Resource servers MAY expire historical change data after a retention period. A changes_since token is valid while the resource server still holds the change history back to and including its horizon. If a client's token has expired, the resource server MUST return HTTP 410 Gone with error code cursor_expired. The client MUST start again from beginning.

Two distinct cursor spaces: cursor/next_cursor are pagination tokens within a single query execution; changes_since/next_changes_since are incremental sync tokens across sessions. A client MUST NOT use a next_cursor value as a changes_since parameter; they are different token spaces and will produce a protocol error if confused. The terminal page of a changes_since result MUST include a next_changes_since field. A non-terminal page MUST NOT include it, because the resource server never issues a token for pages it has not delivered. Paginating an incremental sync: pass changes_since on the first request, follow next_cursor for subsequent pages within that session, then store next_changes_since from the terminal page for the next session.

Tombstones: For a client token, a tombstone is exactly:

{
  "object": "record",
  "id": "canonical-key-string",
  "instance_id": "inst_K4wq8Rn2",
  "stream": "playlists",
  "deleted": true
}

A client tombstone has no data, deleted_at, or emitted_at. It tells the client only that a record visible at the previous horizon is not visible now. It does not reveal whether the record was deleted, when the change happened, or any field value.

For an owner token, a tombstone also carries removal, and for a deletion deleted_at and emitted_at:

{
  "object": "record",
  "id": "canonical-key-string",
  "instance_id": "inst_Zp5rT2mA",
  "stream": "playlists",
  "deleted": true,
  "removal": "deleted",
  "deleted_at": "2026-04-01T10:00:00Z",
  "emitted_at": "2026-04-01T10:00:01Z"
}

removal is deleted when the record was deleted, and left_query when the record still exists but no longer passes the owner's query context, for example a range filter. deleted_at and emitted_at are present only when removal is deleted. The owner owns the data, so the reason is not hidden from them.

Tombstones use the same object: "record" envelope as regular response records, with deleted: true. The id field is the canonical key string (see RECORD envelope, Compound key encoding below), and instance_id names the record's instance.

A tombstone signals that a record left the client's view of the stream. For subset or derived streams this means membership removal; it does not assert that the source record was deleted. See Derived subset streams (Section 12) for the non-normative discussion of this stream shape.

deleted_at represents the time the record was deleted in the source system, if known; otherwise the time the RS processed the deletion directive.

Non-normative note (GDPR Article 15): The version history maintained internally by the resource server to support mutable_state incremental sync may support implementations that choose to expose historical access features to users. Whether such exposure is required is outside the scope of this specification. This alignment is non-normative and is not a required v0.1 capability.

Split rule

When modeling data from a source, apply this rule:

• Separate stream if: has its own stable ID, unbounded cardinality, changes independently, or consumers query it independently.
• Nested within a record if: small, bounded, and only meaningful as part of the parent.

Example: conversations and messages are separate streams (messages are unbounded, have their own IDs, change independently). A message's content_blocks array can be nested (bounded, only meaningful within the message).

This is a common data modeling judgment call. The rule above is a guide, not a formula; declaration publishers exercise discretion.

The RECORD envelope

RECORD is the universal data envelope. It is used in the Collection Profile and is the canonical shape for records stored in the resource server.

{
  "stream": "messages",
  "key": "msg_abc123",
  "data": {
    "id": "msg_abc123",
    "conversation_id": "conv_xyz",
    "role": "user",
    "content": "What is the weather like?",
    "source_created_at": "2026-03-28T15:00:00Z"
  },
  "emitted_at": "2026-03-28T15:01:00Z"
}

Compound key encoding: When primary_key has multiple fields, key is an array of values in the order declared by the SourceDeclaration primary_key. The canonical string form of a compound key is the minified JSON array of key values (e.g., ["user_123","2026-04-01"]). Each primary-key component MUST be serialized as a string in the canonical encoding. Non-string primary-key field values (e.g., integers, dates) MUST be converted to their string representation before encoding. URL path parameters and resources[] entries use percent-encoded canonical string form. The resource_ref.record_id field retains native string | string[] type.

Record identity: For any record, the values of the data fields named by the stream's primary_key MUST match the values in the key envelope field (in order). A resource server or profile-defined write interface MUST reject a record before storage when those values disagree. The Collection Profile defines the HTTP error for its ingest endpoint.

A resource server stores each record under exactly one instance. The canonical key is unique only within one instance of a stream: two instances can hold records with the same key, for example the same playlist in two accounts. Within a stream, a record is therefore identified by its instance_id and its canonical key. Core defines no ingest path, so it does not define how a record is assigned to an instance.

Response records: A query response serves each record as an object with object: "record", id (the canonical key string), instance_id, stream, data, and emitted_at. A tombstone uses the same object with deleted: true (see Tombstones above). instance_id is the opaque handle of the record's instance, and every served record and tombstone carries it. For a client token, it is the handle that the grant lists for that instance. For an owner token, it is the owner's handle for that instance, and every owner-token response uses the same value. A client MUST identify a record within a stream by its instance_id and id together.

Timestamps

Two timestamp concepts appear in records:

• emitted_at: when the producer emitted the record. Always present on the RECORD envelope. Producer-generated.
• Source timestamps: when the event occurred or the resource was created or modified on the source platform. These are fields within data, declared in the stream schema. The spec reserves two standard field names: source_created_at and source_updated_at. Connector authors SHOULD use these names when the platform provides them, rather than inventing platform-specific names.

Foreign keys

Streams reference each other via foreign key fields in data:

{
  "stream": "conversations",
  "key": "conv_xyz",
  "data": {
    "id": "conv_xyz",
    "title": "Weather chat",
    "source_created_at": "2026-03-28T14:00:00Z"
  }
}
{
  "stream": "messages",
  "key": "msg_abc123",
  "data": {
    "id": "msg_abc123",
    "conversation_id": "conv_xyz",
    "content": "...",
    "source_created_at": "2026-03-28T15:00:00Z"
  }
}

The SourceDeclaration declares primary_key per stream. Foreign key relationships are declared in its relationships field (see Section 5). A foreign key refers to a record in the same instance.

Binary data (blob_ref)

Binary data (photos, videos, audio, documents) is not inlined in records. The record contains metadata and a blob_ref:

{
  "stream": "media",
  "key": "media_123",
  "data": {
    "id": "media_123",
    "caption": "Sunset",
    "media_type": "image",
    "source_created_at": "2026-03-28T10:00:00Z",
    "blob_ref": {
      "blob_id": "blob_media_123",
      "mime_type": "image/jpeg",
      "size_bytes": 2048000,
      "sha256": "a1b2c3..."
    }
  }
}

mime_type MUST be a valid IANA media type (see IANA Media Types). Record producers emit blob_ref without a fetch_url. The resource server injects fetch_url at read time when serving records via the query API. A blob_id is unique only within one instance, so the fetch_url carries the blob's instance_id (see Get a blob in Section 8).

Cross-stream references (resource_ref)

When a record references a record in a different stream on the same resource server, use a resource_ref. This is a within-subject, within-server pointer. Cross-user or cross-server references are out of scope in v0.1.

{
  "stream": "tag_assignments",
  "key": "assign_1",
  "data": {
    "tag_id": "tag_sunset",
    "target": {
      "source_id": "https://registry.pdpp.dev/connectors/instagram",
      "stream": "media",
      "record_id": "media_123"
    }
  }
}

A record producer emits resource_ref without instance_id. When source_id is the referencing record's source, the target is in the referencing record's instance. Core does not define how to resolve the target instance of a reference to another source (Section 12).

At read time, in the same way that it adds fetch_url to a blob_ref, the resource server serves each resource_ref in one of two forms. It serves the resolved form, the reference with instance_id added, only when the target record passes every constraint of the requesting token's grant for the target stream: instance, resources, time constraint, and field access to the target's key. The value is the target instance's handle, chosen as for response records. Otherwise it serves the redacted form, which has exactly source_id, stream, and redacted: true, and no record_id or instance_id:

{
  "source_id": "https://registry.pdpp.dev/connectors/instagram",
  "stream": "media",
  "redacted": true
}

For a client token, the token may read the target's instance only when the grant lists that instance's handle for the target stream. In v0.1, the resource server serves every reference to another source in the redacted form. The redacted form replaces the reference in place, and the resource server never drops the field that holds it, even when the stream schema requires record_id inside that field. No other form is served. A client MUST accept a redacted form wherever a resource_ref can appear, and MUST treat it as a reference that it cannot follow.

5. Source Declaration

Each source publishes a SourceDeclaration describing its identity, publisher, consent surface, record semantics, selection capabilities, and Resource Server query capabilities. Connector-backed and provider-native sources use the same Core shape. The declaration defines what can be consented to. The resolved grant defines what was approved.

SourceDeclaration structure

{
  "protocol_version": "0.1.0",
  "source": {
    "kind": "connector",
    "id": "https://registry.pdpp.dev/connectors/spotify"
  },
  "declaration_version": "2026-08-11",
  "publisher": {
    "id": "https://registry.pdpp.dev/"
  },
  "display": {
    "name": "Spotify"
  },
  "selection_presets": [
    {
      "id": "listening_history",
      "label": "Listening history",
      "streams": [
        { "name": "top_artists", "view": "basic" },
        { "name": "play_events", "fields": ["*"] }
      ]
    }
  ],
  "streams": [
    {
      "name": "top_artists",
      "description": "Most-listened artists over time",
      "display": {
        "label": "Your top artists",
        "detail": "Artist names, genres, and popularity scores. No listening timestamps or play counts."
      },
      "semantics": "mutable_state",
      "schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "genres": { "type": "array", "items": { "type": "string" } },
          "popularity": { "type": "integer" },
          "source_updated_at": { "type": "string", "format": "date-time" }
        },
        "required": ["id", "name"]
      },
      "primary_key": ["id"],
      "cursor_field": "source_updated_at",
      "consent_time_field": "source_updated_at",
      "selection": {
        "fields": true,
        "resources": false
      },
      "query": {
        "range_filters": {
          "source_updated_at": ["gte", "gt", "lte", "lt"]
        }
      },
      "views": [
        {
          "id": "basic",
          "label": "Artist names and genres",
          "fields": ["id", "name", "genres"]
        },
        {
          "id": "full",
          "label": "Full artist data",
          "fields": ["id", "name", "genres", "popularity", "source_updated_at"]
        }
      ]
    },
    {
      "name": "play_events",
      "description": "Individual track play events",
      "semantics": "append_only",
      "schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "track_id": { "type": "string" },
          "played_at": { "type": "string", "format": "date-time" },
          "duration_ms": { "type": "integer" }
        },
        "required": ["id", "track_id", "played_at"]
      },
      "primary_key": ["id"],
      "cursor_field": "played_at",
      "consent_time_field": "played_at",
      "selection": {
        "fields": true,
        "resources": false
      }
    }
  ],
  "extensions": {}
}

SourceDeclaration fields

The public SourceDeclaration JSON Schema declares JSON Schema 2020-12. Each streams[].schema uses that dialect when $schema is absent. If $schema is present, it MUST equal https://json-schema.org/draft/2020-12/schema. This dialect choice does not by itself guarantee identical validator behavior. The AS MUST meta-validate each embedded stream schema before accepting the declaration. Embedded $ref and $dynamicRef values MUST be local fragment references. A declaration MUST NOT make consent interpretation depend on a mutable remote schema.

source.id is the authorization identity. In a retained declaration or grant, source.kind records the provenance class that the AS accepted from its declaration authority. It is not authorization equality, a runtime type, or a Collection Profile claim, and it never selects serving or acquisition runtime. A connector declaration with no Collection extension remains valid Core input. The declaration never contains owner-specific account or instance handles. Those appear on each stream in the selection request and resolved grant.

Stream display metadata

Streams MAY include a display object with human-readable metadata for the consent UI. This metadata is authored by the accepted declaration publisher, not the requesting client.

Authorship principle: display.label and display.detail describe the data itself, not the requester's purpose. They are attributed to the accepted declaration publisher. The requesting client MUST NOT override or supplement these descriptions in the selection request. Publisher attribution is authenticated only under the conditions in SourceDeclaration fields.

{
  "name": "following_accounts",
  "description": "Accounts the user follows",
  "display": {
    "label": "Who you follow",
    "detail": "Usernames and account IDs of accounts you follow. No DMs, profile details, or follower lists."
  },
  "semantics": "mutable_state",
  "schema": { "..." : "..." }
}

consent_time_field

The consent_time_field is the field on each record that the resource server evaluates time_range against. It represents the stream's temporal consent boundary: when the user consents to "data from the last 6 months," the consent_time_field is the field that determines whether a given record falls within that window.

The consent_time_field may be the same field as cursor_field, but they serve different purposes and MUST be declared separately:

• cursor_field orders ordinary list reads; changes_since uses a separate RS change-order position.
• consent_time_field governs consent-time filtering (which records fall within the authorized time window).

For many append_only streams, both fields will be the same (e.g., played_at for play events). For some mutable_state streams they may differ. A playlists stream might use source_updated_at as the cursor_field, to order list reads by recent change, but source_created_at as the consent_time_field. The user's consent to "playlists from the last 6 months" most naturally means playlists they created in that period, not playlists they edited.

Field type: A consent_time_field MUST be a top-level field whose schema declares format date (RFC 3339 full-date) or date-time (RFC 3339 date-time, which always has an offset). Every non-null value is a string in that format. The schema MAY allow null. A field of any other type, such as an epoch integer or a timestamp without an offset, is not eligible. The AS MUST reject a declaration that names an ineligible consent_time_field; a publisher may omit the field to offer the stream without time-range selection. A producer that has only such a value can emit an RFC 3339 sibling field and declare that field instead, keeping the original.

Period and summary records: An ordinary record, such as an event or an observation at one instant or on one day, is matched by the single value of its consent_time_field. Some records contain data from outside their own time value, for example a budget month, a billing cycle, a statement, or a coverage receipt. A stream whose records can do this MUST declare consent_time_content_may_exceed: true. For a time-bounded grant on such a stream, the AS MUST tell the owner that matched records can contain data from outside the bounds, and say what the matched value is. The AS MUST NOT present such a grant as limited to data inside the bounds. Aligning bounds to whole periods does not remove this duty, because a period record can carry figures from earlier periods. A declaration SHOULD put summary records, such as coverage receipts, in their own stream.

Rendering: The consent_time_field MUST be rendered in human-readable consent UX, with the declared meaning of the field. A grant with time_range: { since: "2026-01-01T00:00:00Z" } on the playlists stream should be presented as "playlists created at or after 00:00 UTC on 1 January 2026," not just "playlists in time_range." The AS MAY use any language and phrasing that conveys the meaning. For a time-bounded stream:

• The AS MAY show a relative label, such as “last 90 days”, only if the AS has verified that the label is true for that stream’s exact bounds. Otherwise it omits the label.
• For a date field, the consent text MUST state whose day the value is, as the declaration describes it: for example "the day Oura assigns, in your local time" or "the budget date you entered in YNAB". If the declaration does not say how the source assigns dates, the consent text says "the date the source records" and claims nothing more.
• A continuous grant with since and no until MUST be described as covering records since that bound, including new records as they arrive. It MUST NOT be described as a rolling window.
• For a continuous grant, the AS MUST tell the owner that the client can see records leave the window when their time values change (see Time constraint semantics).
• If the field’s schema allows null, the AS SHOULD tell the owner that records without a value are not included.

Streams that cannot define a stable consent_time_field simply omit it. The absence of consent_time_field is the normative signal that the stream does not support time-range filtering.

Relationships

{
  "name": "conversations",
  "relationships": [
    {
      "name": "messages",
      "stream": "messages",
      "foreign_key": "conversation_id",
      "cardinality": "has_many"
    }
  ]
}

Views

Views are named field projections that the authorization server may define for a stream, composed from fields declared in the stream schema. Views are the unit of consent when a client requests access by view name rather than by explicit field list. A view names a field set within a single stream, while a selection preset expands to stream-level selections at request scope.

Declaration publishers MAY suggest views. These suggestions are advisory. The authorization server is authoritative for views used in consent UI and issued grants. The AS MUST NOT define a view that includes fields absent from the retained SourceDeclaration schema for the relevant stream.

View evolution: Grants are bound to the resolved field set at issuance time: fields in the StreamGrant is authoritative, not the view name. View evolution (adding new fields to a view) never silently widens existing grants. Re-consent is required before a client can access new fields, even if those fields are subsequently added to a named view the client already has a grant for.

Authority and registry: Views defined under pdpp.dev URI namespaces are controlled by PDPP maintainers via a public change process. Implementations MUST treat unrecognized view URIs as opaque identifiers.

Versioning and snapshots

declaration_version is an opaque exact revision identifier. Core does not assign semantic-version ordering or compatibility meaning to it. A connector software release can leave the declaration unchanged, and a declaration can change without a connector release.

The authorization server retains the exact declaration snapshot used to validate the request and render consent. It uses that same snapshot for narrowing, issuance, and retained consent evidence. The issued grant records the declaration revision and every resolved authorization fact. A version label alone is not a snapshot.

Adding a field, view, stream, or capability to a later declaration never widens an existing grant. Removing or changing a currently served capability may make a request technically unsupported, but it does not reinterpret what the user approved. The Resource Server enforces the resolved grant without a current declaration lookup. Current serving metadata may only route, describe current capabilities, narrow, or reject.

Declaration acceptance

An authorization server accepts a source declaration only through explicit owner or operator onboarding, an installed catalog, an accepted registry entry, or explicit local provisioning. A client MUST NOT introduce a new source authority or declaration URI during authorization.

For a provider_native source, source.id MUST be identical to the protected-resource identifier the authorization server has already accepted for that resource. The authorization server MUST reject any mismatch before consent or grant issuance.

publisher.id is an unauthenticated claim unless an accepted channel or configured mapping binds that publisher to the declaration. Without such a binding, the authorization server MUST NOT rely on publisher.id for source acceptance, attribution, redirect policy, or any other trust decision.

An accepted revision is keyed by its accepted authority binding, source.id, and declaration_version. Different parsed content under an accepted key is equivocation: the authorization server MUST reject it and retain the previously accepted content, and MUST NOT infer ordering or freshness from declaration_version.

When retrieving a declaration, the authorization server MUST use HTTPS without ambient credentials. It MUST validate every redirect target and the final URL against its accepted declaration pointer and network policy. It MUST reject a declaration that requires automatic retrieval of a remote schema, and MUST fail closed when any check fails.

The address check is bound to the connection, not to the URL. The authorization server MUST validate the destination address against its network policy immediately before each connection attempt, including each redirect hop. It MUST connect only to an address from that validated result. An address accepted for an earlier attempt does not authorize a later resolution. The declaration location is not the source identity. Section 10 states the retrieval limits an authorization server sets by local judgment.

Declaration display values are untrusted input. An authorization server MUST render declaration display values safely for the output context, by context-appropriate escaping, by sanitization, or by any construction that guarantees the value cannot be interpreted as markup, script, or a control sequence in that context. The requirement is on the outcome; this specification does not mandate one technique. Current declaration capabilities MUST NOT widen an issued grant.

6. Selection Request

A client requests specific personal data by including authorization_details in an OAuth 2.0 authorization request, following RFC 9396.

{
  "response_type": "code",
  "client_id": "music_recommendations",
  "redirect_uri": "https://app.example.com/callback",
  "scope": "openid",
  "client_display": {
    "name": "Concert Finder",
    "uri": "https://concertfinder.example.com",
    "logo_uri": "https://concertfinder.example.com/logo.png",
    "policy_uri": "https://concertfinder.example.com/privacy",
    "tos_uri": "https://concertfinder.example.com/terms"
  },
  "authorization_details": [
    {
      "type": "https://pdpp.dev/data-access",
      "source": { "id": "https://registry.pdpp.dev/connectors/spotify" },
      "purpose_code": "https://pdpp.dev/purpose/personalization",
      "purpose_description": "Recommend concerts based on your listening history",
      "access_mode": "single_use",
      "streams": [
        {
          "name": "top_artists",
          "necessity": "required",
          "view": "basic",
          "instance_ids": ["inst_K4wq8Rn2"],
          "time_range": { "since": "2025-09-28T00:00:00Z" }
        },
        {
          "name": "play_events",
          "necessity": "optional",
          "fields": ["*"]
        }
      ],
      "client_claims": {
        "commitments": ["Data used only for concert recommendations"]
      }
    }
  ]
}

Client display metadata

The top-level client_display object carries inline client display metadata for the requesting application. PDPP reuses the human-readable client metadata model from OAuth 2.0 Dynamic Client Registration (RFC 7591 Section 2.2), but transports it inline in the authorization request rather than requiring a dynamic client registration endpoint.

Inside client_display, PDPP drops the client_ prefix from client_name and client_uri because the enclosing object is already client-scoped. The metadata model is otherwise aligned with RFC 7591.

client_display is entity-scoped: it describes the client, not a specific authorization request. It appears at the top level of the authorization request, outside authorization_details.

client_display is an inline carrier, not necessarily the AS's final rendered identity record. The AS MAY replace or augment inline values with locally registered metadata, validated binding metadata, validated software-statement metadata, or trust-registry metadata.

Validated binding metadata is client metadata the AS obtained and verified through the mechanism that binds the client to the authorization protocol in use, rather than metadata the client asserted inline in this request. Under the OAuth binding it is the metadata a client ID metadata document or a dynamic registration record supplies, after the binding's own validation succeeded. Core does not define how a binding validates it; Core defines only that validated binding metadata outranks inline client_display, because the AS checked it and the client did not merely assert it.

URL-hosted client identity. A client ID metadata document is valid for this rule when three conditions hold. It is syntactically valid per the client ID metadata document specification the OAuth binding names. The authorization server retrieved it over HTTPS from the client_id URL itself. And the client_id inside the document is identical to the URL it was retrieved from — the check that stops a document from claiming to be a different client.

Two obligations follow, and they are separate. The interoperability obligation: a conforming authorization server MUST NOT reject a valid client ID metadata document solely because the client is not preregistered. The local-authority obligation, which the first does not weaken: the server MAY still deny authorization, rate-limit the client, or require a registry-derived trust or admission result, under local policy and for any reason other than the absence of preregistration. A conformance test therefore exercises two distinct outcomes — an unregistered valid document that is accepted as an identity, and a policy denial that is not a rejection of the identity form.

For PDPP Core v0.1 interoperability, a conforming authorization server MUST accept a valid URL-hosted client identity unless local policy denies authorization.

Metadata resolution and rendering obligations:

1. The AS MUST resolve requester identity metadata from the best available source. Source precedence is local registration or trust-registry metadata, then validated software-statement metadata if supported, then validated binding metadata, then inline client_display, then client_id fallback.
2. If the resolved metadata contains a display name, the AS MUST display it to the user during consent. If no display name is available, the AS MUST display client_id as the requester identity.
3. If the resolved metadata contains policy_uri or tos_uri, the AS SHOULD present each during consent. If it issues a grant, the corresponding field in client.client_display MUST contain the exact URI presented as text or as a link target; a URI not presented MUST be omitted from that field. A recorded URI identifies the target presented during consent; it does not preserve the linked document's contents.
4. If the server has a positive trust signal for the client (e.g., verified domain control, trust registry membership), it MUST render that status distinctly (e.g., a “verified” badge). If it has no positive trust signal, it MUST treat the client as unverified and SHOULD display an “unverified app” indicator.
5. Domain control as a trust signal. The binding may identify a client by a URL that client controls. Where the AS both retrieved that client's metadata from that URL over HTTPS and confirmed the retrieved document identifies the same client, the AS has verified that the client controls that domain. The AS MAY treat verified domain control as a positive trust signal under obligation 4, and when it does it MUST name the verified domain rather than assert an unqualified verification (for example "Verified domain: example.com", not "Verified app"). Domain control establishes only that the operator of that domain published this client's metadata. It is not an assertion about the client's conduct, its data practices, or any review by the AS operator, and the AS MUST NOT present it as one.
6. The AS MUST treat logo_uri as untrusted content until it has been accepted under local policy. It MUST NOT fetch and render a client-supplied remote logo in the consent UI unless the client is verified or the asset has been proxied, cached, and approved under local policy. For unverified clients, the AS SHOULD generate a monogram from the resolved display name.
7. If neither resolved metadata nor inline client_display provides a display name, the consent UI SHOULD clearly indicate that the client has not provided display metadata.

Pre-registered public client discovery

An authorization server MAY support clients that are public and pre-registered by the deployment rather than dynamically registered. Dynamic public-client self-registration is the preferred discoverable path when registration_endpoint is advertised. When AS metadata advertises pre_registered_public in pdpp_registration_modes_supported, the reference publishes pdpp_pre_registered_public_clients so agents and third-party clients can discover usable fallback or example client_id values without an out-of-band walkthrough.

Each pdpp_pre_registered_public_clients entry contains client_id, client_name, and token_endpoint_auth_method. These entries are public client metadata, not authority to access data. The user grant remains the authorization boundary, and the field MUST NOT contain secrets, access tokens, owner-scoped clients, dynamically registered clients, or private registration state.

Client claims

The optional client_claims object within each authorization_details entry carries client-authored, non-enforceable statements about the specific authorization being requested. These are request-scoped, not entity-scoped: a client may make different commitments for different authorization requests.

Trust boundary: Client claims are self-asserted and unverifiable by the server. The AS MUST render client_claims content separately from protocol-enforced grant terms and MUST attribute it to the client (e.g., "[client name] says:"). The AS MUST NOT render client claims in the same visual register as protocol-enforced grant terms, structured policy declarations, or declaration-authored data descriptions.

If rendered on the final owner review surface, client_claims MUST be normalized and bound exactly, with client attribution, into the immutable final approval artifact and review revision. Retained consent evidence MUST preserve that binding. They are material consent context, not grant rights. They remain outside authorization equality, the resolved grant, introspection rights, and RS enforcement.

Relationship to purpose_description: purpose_description is a first-class request field describing what the authorization is for. It is part of the authorization semantics the user reviews. client_claims.commitments are supplementary promises that are not reducible to structured protocol fields. Both are client-authored, but purpose_description is the primary purpose statement while commitments are additional assurances.

Commitments that ARE machine-readable: Structured grant fields (e.g., retention.max_duration, access_mode) SHOULD be rendered by the AS as server-generated display text (e.g., "Deleted within 90 days", "Ongoing access until you revoke it"). Clients SHOULD NOT duplicate machine-readable constraints as free-text commitments. If a commitment duplicates a structured field, the structured field is authoritative.

Semantic classes and consent-surface rendering

PDPP uses three primary semantic classes across selection requests and grants:

• Protocol-enforced constraints: Values the AS and/or RS actually validate or enforce, such as stream selection, field projection, time_range, resources, access_mode, and the closed processing_permissions set.
• Structured policy declarations: Machine-readable statements that matter for consent, local policy, and implementation-defined audit or transparency mechanisms, but are not generally self-enforcing at the protocol layer. In v0.1 this includes purpose_code, purpose_description, and retention. None of them confers a processing permission.
• Attributed client claims: Client-authored statements that may matter to the user but are not protocol facts. In v0.1 this is client_claims.

client_display is a separate category: requester identity metadata used to identify who is asking, not a grant constraint. Inline values may be client-asserted, but the AS renders them under its own resolution and trust policy.

PDPP does not standardize consent screen layout, visual design, or copywriting. It does normatively constrain semantic rendering. A conformant AS MUST preserve the distinction between protocol-enforced terms, structured policy declarations, declaration-authored data descriptions, and client-authored claims. It MUST NOT flatten these categories into a single undifferentiated consent surface.

Request-level parameters

Source kinds

These are the two provenance classes an authorization server derives and carries forward. They are defined here because this is where a reader meets the source binding, not because a client sends one.

A selection request does not carry source.kind. The authorization server derives the provenance class from the declaration it accepted for source.id, and records it in consent evidence and any issued grant, where a client reads it back through introspection. A client whose policy depends on provenance therefore reads it from the issued grant rather than asserting an expectation in the request; Section 9 states that as a client requirement. The OAuth/RAR binding returns RFC 9396 invalid_authorization_details for invalid authorization details.

An authorization server MUST reject a declaration containing an unrecognized source.kind. A resource server MUST NOT interpret an unrecognized grant source.kind as a known provenance class. A client that reads an unrecognized source.kind in a grant MUST NOT treat it as either known value; it MAY reject the grant as unsupported. A later version can add provenance classes; an implementation that predates one does not misread it as a known class.

Processing permissions

A processing permission authorizes an operation on disclosed data that read access alone does not authorize. A selection request and a grant carry processing permissions in processing_permissions, a set of unique absolute-URI identifiers. Absent or empty means no processing permission. An issued grant carries the member only when the set is non-empty. processing_permissions is a Core field, not an extension. A purpose code, purpose_description, client_claims, retention, or extension never confers a processing permission.

Each identifier has one defining specification, which states the operation the permission covers and how a recipient maintains and exercises the authority. Core defines one identifier:

Closed issuance. The AS MUST reject a detail whose processing_permissions is not an array of absolute URIs, or contains a duplicate, unknown, or unsupported value. The OAuth/RAR binding returns RFC 9396 invalid_authorization_details. The AS MUST NOT ignore, substitute, or narrow such a value, and MUST NOT issue an ordinary grant in place of the detail.

Example. Until the AI Training Profile is registered, every AS receives this detail as unsupported:

{
  "type": "https://pdpp.dev/data-access",
  "source": { "id": "https://registry.pdpp.dev/connectors/spotify" },
  "purpose_code": "https://pdpp.dev/purpose/personalization",
  "purpose_description": "Train an on-device model that ranks concerts for Concert Finder",
  "access_mode": "single_use",
  "processing_permissions": ["https://pdpp.dev/processing/ai_training"],
  "streams": [{ "name": "play_events", "fields": ["*"] }]
}

The AS returns invalid_authorization_details. It issues no training grant and no ordinary grant in its place.

Discovery. An AS lists the permissions it supports in pdpp_processing_permissions_supported, an array member of its RFC 8414 authorization-server metadata. Absent or empty means the AS supports none. An AS MUST NOT advertise or grant a permission unless it implements the permission's complete defining contract. A client MUST NOT request a permission that the AS does not advertise.

Registration. Only this specification, or a profile registered under a Specification Required policy (RFC 8126 Section 4.6), defines a processing permission. A registration gives the identifier, its stable semantics, and exactly one defining profile and version, and the decision to approve it is publicly recorded. A client, deployment, or extension cannot define a processing permission. The registered defining profile and version are an immutable normative reference for the permission identifier. Registry maintainers MUST NOT replace that reference with a different profile or version. A grant retains the authority and owner protections of that registered version, including for subsequent issuance or renewal of processing authority. Publishing a later profile version does not change this binding. A profile revision MUST NOT widen that authority or reduce those protections. Publishing a revision MUST NOT retroactively invalidate previously issued processing authority or make conduct permitted by the bound version non-conformant. An AS MAY issue shorter-lived or more restricted processing authority when the bound version permits it. Binding grants to a different defining profile or version requires a new permission identifier and fresh owner approval.

Consent and evidence. A client MUST request a processing permission in its own detail, separate from any detail for ordinary access, even for the same source and purpose. The owner MUST select that detail by a distinct affirmative action, even when it is the only detail. The AS MUST NOT present it as selected by default. The owner MUST be able to approve every other detail while declining it, and the AS MUST NOT make approval of another detail depend on it. The AS MUST render each permission as a distinct, labeled term, not as part of the purpose.

The owner approves or declines the detail as a whole. The AS MUST NOT issue its grant without its permissions, and MUST NOT add a permission to a detail that did not request it. Approval of ordinary access never confers a processing permission. The final approval artifact, review revision, retained consent evidence, issued grant, token result, and introspection result MUST carry the exact permission set. If the set changes after review, including by removal, the AS MUST reject approval and require a new review.

AI training

https://pdpp.dev/processing/ai_training covers AI training. AI training means using data to fit or select the learned parameters or stored examples of a machine-learning model, generative or not, wherever the model runs, including on-device personalization and federated updates. It includes fine-tuning, distillation, reinforcement learning, and evaluation used to select a model, checkpoint, or hyperparameters. Fitting a model whose learned state is its stored examples, such as a nearest-neighbour classifier, is AI training. Inference, retrieval, embedding generation with fixed parameters, building an index that a fixed model looks up, and measurement that never informs model selection are not AI training. Computing statistics, ranking by a fixed formula, and setting thresholds by hand are not AI training. For example, recommending concerts from a listening history with a fixed model is not AI training; fitting a per-owner recommendation model to that history is. This permission governs clients acting under grants. It does not limit what the owner does with data the owner exports.

A PDPP input is data obtained through PDPP, or data derived from it, including through successive transformations. Derivatives include labels, synthetic examples, embeddings, and outputs generated using PDPP inputs. A model output inherits the lineage of PDPP inputs used to produce that output. Earlier use of an owner’s data to train the model does not, by itself, make the output a derivative of that owner’s data.

A client MUST NOT use a PDPP input for AI training unless it has valid processing authority under the permission's defining profile for every contributing PDPP input. For data obtained through PDPP, a grant carrying https://pdpp.dev/processing/ai_training MUST cover the originating subject, source, stream, instance, fields, resources, and time constraint. The client MUST establish that coverage using authenticated issuer, subject, and client bindings; matching identifier strings alone is insufficient. For derived data, the coverage requirement applies recursively to every contributing PDPP input, subject to the model-output boundary above. Different grants MAY cover different contributing inputs. The acquisition grant need not be the training grant. If the client cannot establish coverage and valid authority for every contributing PDPP input, it MUST NOT use the input for AI training. Purpose codes, ordinary grants, and retention commitments never confer this authority. Every recipient or subprocessor to which a client passes PDPP inputs MUST observe the same restriction, and the client MUST impose it on them. An operator of an AS or RS MUST NOT use owner data that it holds in that role for AI training, except under a training grant issued to it as a client. This restriction is PDPP policy, independent of a recipient's lawful basis and of statutory rights.

The PDPP AI Training Profile (forthcoming) defines how a training recipient maintains and exercises this authority. Until that profile is published and its registration as the defining profile is approved, the identifier is reserved. Every AS MUST treat it as unsupported: it MUST NOT advertise it and MUST reject a request that carries it. No grant can then carry it, so no client or operator holds AI training authority.

Earlier drafts expressed AI training as the purpose code https://pdpp.dev/purpose/ai_training. A grant that carries that code confers no AI training authority. Training requires a fresh grant that carries this permission.

AI training consent

A detail that carries the AI training permission MUST include a non-empty purpose_description that identifies the type of model, its functions, and the service or recipient it serves. The AS MUST reject such a detail without one, with invalid_authorization_details in the OAuth/RAR binding. The AS MUST label the detail as AI training on the approval surface. These rules add to Consent and evidence and to the final owner approval that every grant needs (Section 7). An AS MUST include expires_at in every grant carrying the AI training permission. The expiry MUST be later than issued_at. The AS MUST include that expiry in final owner review and bind it into the approval artifact and retained consent evidence.

Stream selection parameters

Per-stream, within the streams array. name and exactly one of a non-empty fields list or a view are required; the other fields are optional.

Note on fields: At consent resolution, schema-required fields are always included in the resolved field set, regardless of the requested field list, because a record missing its schema-required fields is not a valid record of that stream; the per-stream consent floor is its required fields.

The resolved selection MUST contain at least one field for each retained stream.

Note on time_range: time_range is only valid for streams that declare a consent_time_field. The authorization server MUST reject selection requests that specify time_range on a stream without that field. Its presence in the retained declaration is the authoritative signal that a stream is time-range-capable.

Time range bounds: Each bound MUST have the type of the stream's consent_time_field: a full-date for a date field, and a date-time for a date-time field. A time_range MUST contain since, until, or both. The AS MUST reject a time_range with no bound, a bound of the wrong type, a bound that is not valid under Time constraint semantics, or a since that is not before until. The OAuth/RAR binding returns RFC 9396 invalid_authorization_details, as for other invalid details; error_description MAY name the failed check. The AS MUST NOT convert or round a bound. A client reads each field's format from the declaration and sends bounds of that type per stream.

A wildcard entry MUST be the only entry in streams. Otherwise stream names MUST be unique within the request.

Note on streams vs selection_preset: Exactly one is required. Source validation fails if both or neither are present. The OAuth/RAR binding maps this failure to RFC 9396 invalid_authorization_details.

Defaults: Each stream request, including each stream in a selection preset, MUST carry either fields or view. There is no implicit "all fields" default: a client that wants every permitted field sends fields: ["*"], which the AS resolves against the retained snapshot. The marker is valid even when the stream declares selection.fields: false. The OAuth/RAR binding maps a stream request with neither fields nor view to RFC 9396 invalid_authorization_details. Omitting necessity means optional. Omitting time_range asks for no temporal constraint. Omitting instance_ids never asks for fan-in. The issued grant contains explicit non-empty fields and instance_ids. Clients SHOULD request only the data they need (see Section 11, Data Minimization).

Request resolution

The AS MUST expand presets, views, and wildcards against the retained declaration before applying owner choices. It MUST resolve the request into explicit grant constraints before final approval. It MUST preserve the client identity associated with the authorization request.

Limits and owner choices

Explicit requested instances, resources, and time bounds are upper limits. For fields, the upper limit is the field ceiling: the stream's expanded requested fields together with its schema-required fields. The AS MUST compute the ceiling before owner narrowing and minimum checks. The AS MUST NOT resolve outside those limits. Each stream names non-empty fields, a view, or fields: ["*"]; there is no implicit field selection. An omitted time range remains unbounded. Omitted instance handles retain the exactly-one-or-owner-choice rule.

The AS MAY let the owner remove optional streams and narrow retained streams, but not below a stream’s schema-required fields. The AS MUST NOT infer a client requirement from a schema-required property. It MUST retain each required stream or refuse the authorization. Narrowing a required stream does not itself constitute refusal if its explicit minimum remains satisfied.

The AS MUST refuse issuance when the owner approves no streams. It MUST NOT add another source, stream, instance, field, or resource to compensate for a refused selection. A different proposal requires a new authorization request or an explicitly defined owner-selection binding.

An AS MAY present bundles, contextual choices, or detailed controls. It MUST show the resolved disclosure and commitments before final approval. It MUST NOT present optional selections as compulsory. Core does not require a separate toggle for each selector.

Explicit authorization minima

The AS MUST recognize only fields and time_range inside minimum. It MUST reject empty minimum objects, unknown minimum members, duplicate field names, and fields outside the stream's field ceiling. A supplied minimum.fields MUST be a non-empty array of declared top-level field names.

For a retained stream, the AS MUST include every minimum.fields member in the resolved field selection. The AS MUST NOT treat a schema's required array as minimum.fields. For an optional stream, failure to satisfy its minimum permits omission of that whole stream, not a weaker retained stream.

A supplied minimum.time_range MUST contain both since and until. Each bound MUST have the type of the stream's retained consent_time_field and MUST be valid under Time constraint semantics. since MUST be before until. The AS MUST NOT convert or round a bound. The AS MUST reject a minimum window outside the requested time window or on a stream without consent_time_field. It MUST resolve a retained stream to a time window containing the entire minimum window.

For these checks, an absent resolved lower bound means negative infinity and an absent upper bound means positive infinity. Comparisons follow Time constraint semantics: calendar order for date values and exact instant order for date-time values, never string order. Boundaries retain the inclusive-lower, exclusive-upper semantics of time_range.

The AS MUST refuse issuance if an owner-approved required stream cannot meet its minimum. The OAuth binding MUST report this refusal as access_denied. Malformed or unsupported authorization details instead produce invalid_authorization_details. Error descriptions MUST NOT reveal unapproved source, instance, record, or field existence.

An authorization minimum describes permission, not the presence, freshness, completeness, or suitability of records. The AS MUST NOT require records to exist to satisfy an authorization minimum. A client MUST evaluate application sufficiency separately. Core does not define arbitrary predicates over records as issuance conditions.

Recipient commitments and approval

The AS MUST NOT interpret narrower access as recipient acceptance of a new purpose or retention obligation. It MUST resolve purpose and retention from the current request or applicable recipient-authorized standing terms before owner approval. It MUST retain the evidence identifying those terms and their version with the consent evidence.

An AS MUST NOT treat a capability advertisement or owner-authored condition alone as recipient acceptance. When an owner condition is not covered by recipient authority, the AS MUST refuse issuance or obtain recipient acceptance before presenting the revised final approval. No particular acceptance transport is required by Core.

Core represents these commitments through its existing purpose and retention fields. It does not define additional terms fields or a general agreement object. An AS MUST NOT claim that an unrepresented owner condition is a Core grant constraint. A companion that adds recipient obligations MUST define their result representation and acceptance evidence.

The AS MUST NOT change access_mode merely as a consequence of narrowing data. The AS MAY choose grant expiry under its existing policy. Grant lifetime and record time scope remain separate.

The AS MUST include the resolved purpose in final owner review. It MUST include that purpose in the grant. If retention is specified, the AS MUST include it in final owner review. It MUST include that retention in the grant. If grant expiry is specified, the AS MUST include it in final owner review. It MUST include that expiry in the grant. The AS MUST include any processing permissions in final owner review and in the grant, as Processing permissions defines.

The AS MUST complete required-stream and minimum checks before issuing a grant or a client token. It MUST NOT issue a temporary overbroad grant while choices are unresolved. Grant issuance does not authorize unrelated collection, billing, or source-side actions.

Selection presets

Source declarations may define selection presets. A client can reference a preset instead of constructing explicit stream selections:

{
  "type": "https://pdpp.dev/data-access",
  "source": { "id": "https://registry.pdpp.dev/connectors/instagram" },
  "purpose_code": "https://pdpp.dev/purpose/personalization",
  "access_mode": "single_use",
  "selection_preset": "social_summary"
}

The authorization server expands the preset from the retained snapshot into explicit streams and fields before final owner review and issuance. Each selection preset MUST NOT contain the same stream name more than once. Duplicate stream names make the declaration invalid. They are not deferred to grant issuance.

Every field in the issued grant is derived from the selection request, explicit owner resolution, client registration, or authorization server policy. Recipient commitments additionally require the authority described in Request resolution. The grant never contains values whose source is ambiguous.

7. Grant

A grant is an immutable consent artifact. It is the output of the authorization flow.

The authorization server issues an access token bound to the grant. The client uses the access token (not the raw grant) to authenticate with the resource server. The resource server resolves the token to the grant and enforces its constraints on every request. Grant lifecycle (active, expired, revoked) is tracked by the authorization server, not stored in the grant itself.

A grant covers one subject, one source, and one purpose. This is a granularity rule, not an identity rule: grant_id identifies a grant, and two grants MAY have the same subject, source, and purpose. An authorization request MAY carry several authorization_details entries. The owner approves or declines each entry on its own, and each approved, resolved Core data-access detail yields one grant with its own lifecycle. A companion binding that expands one requested detail into several resolved details MUST define them and MUST correlate every requested detail with its outcome. No permission is built by combining grants: the constraints of one grant authorize each disclosure, even when one credential covers several grants.

{
  "version": "0.1.0",
  "grant_id": "grt_8f72a1b3",
  "issued_at": "2026-04-06T15:00:00Z",
  "subject": { "id": "sub_Jq4tN8wR" },
  "client": { "client_id": "music_recommendations" },
  "source": { "kind": "connector", "id": "https://registry.pdpp.dev/connectors/spotify" },
  "source_declaration": { "version": "2026-08-11" },
  "purpose_code": "https://pdpp.dev/purpose/personalization",
  "purpose_description": "Recommend concerts based on your listening history",
  "access_mode": "single_use",
  "streams": [
    {
      "name": "top_artists",
      "instance_ids": ["inst_K4wq8Rn2"],
      "fields": ["id", "name", "genres", "popularity", "source_updated_at"],
      "time_constraint": {
        "field": "source_updated_at",
        "type": "date-time",
        "since": "2025-09-28T00:00:00Z"
      }
    }
  ],
  "retention": {
    "max_duration": "P1Y",
    "on_expiry": "delete"
  },
  "expires_at": "2027-04-06T00:00:00Z"
}

Grant fields

The following field table is normative. Section 13's TypeScript types are a non-normative convenience mirror; on conflict, this table wins.

StreamGrant fields

Request-only conveniences such as wildcard names, the * field marker, view, and omitted instance handles are fully resolved before final owner review and issuance. They are not continuing authority in the grant. Selection provenance may be retained at grant level through selection_preset; the concrete stream rows remain authoritative.

Before the final approval surface is shown, the AS MUST resolve omitted instance_ids to exact eligible instance handles or require an explicit owner choice. For a stream with resources, that choice is exactly one instance. The final approval artifact MUST include the exact resolved instance_ids, stream names, fields, resources, temporal field, since stated as inclusive, until stated as exclusive, purpose, retention, processing permissions, client identity, and grant expiry. If client_claims are rendered during final review, the final approval artifact and review revision MUST also bind the normalized exact claims with client attribution. Retained consent evidence MUST preserve that binding. The approval mutation MUST bind to an immutable review revision or digest over the authorization decision fields. client_claims MUST remain outside the resolved grant and RS enforcement. If instance eligibility or the reviewed revision becomes stale before approval, the AS MUST reject approval and require a new review.

Client-visible authorization result

The AS MUST return one authorization_details element per covered grant in every successful OAuth token response that issues a client access token, including refresh responses. Each element MUST contain type equal to https://pdpp.dev/data-access and grant containing the complete immutable grant defined by this section. The AS MUST NOT substitute the original selection request or a lossy summary.

The result MUST include source provenance, declaration revision, resolved streams, instance handles, fields, resource and time constraints, recipient commitments, access mode, and processing permissions and grant expiry when present. The full grant includes the resolved client identity and reviewed client display defined above. Omitted optional streams are not grants and MUST NOT appear as authorized in the result.

The client MUST inspect the result before requesting record disclosure. It MUST NOT infer authorization from its original request, an MCP tool listing, or a token’s syntax. A client unable to obtain or interpret the result MUST NOT request disclosure. An AS MAY omit only values that the grant definition itself makes optional.

For a token covering multiple grants, the AS MUST return every covered grant as a separate element. It MUST NOT merge fields, instances, or resources across grants. A binding supporting such tokens MUST preserve each grant’s source and client association during enforcement.

The AS MUST return the same resolved grant facts to the client and to an authenticated RS, apart from token-specific active-state and expiry fields. Receiving this result does not grant the client access to the RS-authenticated introspection endpoint. The AS MUST protect result delivery as part of the authenticated OAuth exchange.

Owner approval covers disclosure of the result's identifiers and metadata to the client. The AS MUST NOT include inventory for unapproved sources or instances. A successful token response consumes a single_use grant as defined below even if the client subsequently declines to read.

Pairwise identifiers

Every identifier for the subject, a grantor, or an instance that a client receives is pairwise, as OpenID Connect Core 1.0 Section 8.1 defines for sub. This covers subject.id, each grantors[].id, and each instance handle, in a grant, a record, or any other response to the client. The AS MUST give different clients different identifiers for the same subject, grantor, or instance. It MUST give one client the same identifier for that subject, grantor, or instance in every grant and response, and MUST NOT reassign the identifier to another subject, grantor, or instance. The identifier MUST NOT be reversible by clients: a client cannot derive the internal identifier, or another client's identifier, from it. A value such as clientA:user123, which joins a client name to an internal identifier, does not meet this rule. Clients that share an OpenID Connect sector identifier count as one client for these rules.

These rules also cover the sub claim of an OpenID Connect ID Token that the AS issues to the client. That claim identifies the person who authenticated. When a representative listed in grantors authenticates, sub is that representative's pairwise identifier, the same value as their grantors[].id, and not the subject's.

A per-client decentralized identifier (DID), such as a pairwise or peer DID, meets this rule and MAY serve as the pairwise identifier. The one exception is owner choice. The AS MAY use a globally resolvable identifier, such as a DID, as a client's subject.id only when the owner explicitly chooses to disclose it to that client. The final approval artifact MUST bind the exact identifier and the receiving client, and retained consent evidence MUST preserve that binding. Core defines no other use of such an identifier (Section 12). The choice is fixed for that subject and client before the client's first grant. The AS MUST NOT change a client's subject.id between the pairwise value and the chosen identifier in a later grant.

The AS and RS MAY also keep an internal subject identifier, which passes only between them. In a separated deployment, the AS returns it to the RS as the introspection subject_id, and the RS uses it to find the subject's data (Section 8). The RS MUST NOT disclose it to a client. An introspection result or grant that the AS returns to a client carries only that client's pairwise identifiers. The RS maps a client's handles to stored instances only through pdpp_instance_bindings (Section 8), which the AS never returns to a client.

These rules stop clients from correlating one owner through the identifiers above. They do not make disclosures unlinkable. Record keys, blob_id values, content hashes such as sha256, timestamps, and other record content can still link one owner's disclosures across clients.

Representative approval

A grant covers its subject's data. Usually the subject approves it. When another person approves on the subject's behalf, for example a parent for a child or a legal representative for an adult who cannot act, the grant lists that person in grantors. When several people must approve together, each is listed, and each approved the same final approval artifact.

An authorization server that issues a grant with grantors MUST:

1. authenticate each listed grantor;
2. verify, before showing a prospective grantor any subject-specific information or accepting their approval, that the grantor may approve the complete proposed disclosure under an explicit deployment or profile policy. Where that policy requires several grantors to approve together, the verification covers the complete set. The disclosure includes its selected data, client, purpose, access mode, and duration. The AS MUST reject approval when verification fails. How the AS establishes that authority, for example from a legal document or an authoritative register, is a deployment or profile choice;
3. show each grantor, on the approval surface, that they approve on the subject’s behalf and in which capacity;
4. bind each grantor and capacity into the final approval artifact with the other decision fields;
5. never record a grantor’s identity as the subject.

Appearing in grantors does not by itself authorize later reads, owner operations, or management of the grant. The AS establishes a person's current authority when such an operation is requested.

An AS that does not support representative approval never issues a grant with grantors. A resource server enforces a grant with grantors exactly as any other grant; grantors records who approved and does not change what the grant authorizes. A client may use it in its own admission policy.

Time concepts

The grant carries three orthogonal time-related concepts that must not be conflated:

A grant can be short-lived (expires in 1 hour) but cover all historical data (no time_constraint). A grant can be long-lived but cover only data from the last 6 months (time_constraint.since). A grant can be single_use but cover a large historical window. These combinations are all valid and distinct.

Version layering

Three independent version axes exist in PDPP. They MUST NOT be conflated:

The current persisted-authorization-state reader MUST reject any persisted authorization state whose version or shape it cannot validate against a supported contract before its caller continues introspection or route handling. The reader MUST NOT reconstruct missing authorization or binding facts from current configuration. A deployment that cannot support or explicitly migrate such state MUST require fresh consent.

Access modes

Read access and processing authority

A grant that carries a processing permission confers two distinct kinds of authority. Read access lets a client obtain records through tokens that the RS enforces. Processing authority lets a client perform the permitted operation on PDPP inputs it holds, as the permission's defining profile governs. Token activity, introspection active, and the single_use read window describe read access only.

• The end of a single_use read window, or the expiry of an access token, does not by itself end processing authority.
• A processing credential never confers read access. It never makes a token active or reopens a read window.
• When a grant is revoked, read access ends and the AS MUST issue no further processing authority under it. Authority already issued ends within the cessation bound that the defining profile sets. Revocation here includes owner revocation, client-initiated revocation that ends the grant (Section 10), and a companion operation that ends the grant.
• If a grant has expires_at, processing authority ends no later than that time. The AS MUST NOT issue processing authority that outlasts it.
• Replay detection on a refresh-token family (Section 10) invalidates that family’s tokens, and with them read access through those tokens. It does not by itself end processing authority.
• Ending one grant does not end processing authority under another grant.

The defining profile defines how processing state is represented, the credentials that carry processing authority, and how processing ceases. Core does not require a grant-status endpoint.

Time constraint semantics

The selection request's time_range is resolved against the retained stream consent_time_field into the grant's time_constraint. The grant freezes that field, its type, and the bounds. The filter is:

record[time_constraint.field] >= time_constraint.since  (if since is present)
record[time_constraint.field] <  time_constraint.until  (if until is present)

Comparison: The resource server compares values by the grant's frozen time_constraint.type, never by a current declaration. It compares date values by calendar order. It compares date-time values as instants at their full stated precision: it does not round, and it compares fractional seconds exactly. It MUST NOT apply a host, viewer, or owner time zone. Comparing RFC 3339 strings as text is wrong when their offsets differ.

Validity: A value or bound is valid only if it is a valid RFC 3339 value of its type: time_constraint.type for a grant, or the declared format for an owner filter. Every form RFC 3339 Section 5.6 allows is accepted, including lowercase t and z and fractional seconds of any length. -00:00 is a UTC instant with an unknown local offset; it compares as UTC. A leap second (:60) is valid only if, normalized to UTC, it is 23:59:60 on a date on which a leap second was inserted, per the IERS leap-second table (RFC 3339 Section 5.7). It orders after :59 of the same minute and before the next minute. JSON Schema format is an annotation by default, so implementations MUST apply these rules themselves.

Missing values: A record whose time_constraint.field value is absent, null, or not valid fails the filter. This applies on every read surface: list, single record, changes_since, and blob. The resource server SHOULD report a present but invalid stored value to the operator. Core does not require every record in a time-bounded stream to have a value.

Other time fields: The window restricts which records are returned. It does not restrict other time fields inside a returned record. A transaction booked inside the window can carry a value date outside it, and the client sees that value date if the field is granted.

Incremental sync: A time-bounded grant uses the visibility rules in Incremental sync. A record outside the window at h0 and inside it at h1 is returned. A record inside the window at h0 and outside it at h1, or without a valid value at h1, produces a tombstone. The bounds are frozen, so the passage of time alone does not change which records are visible. When time_constraint.field is not a granted field, the tombstone still tells the client that the record crossed a bound. Incremental sync states that the hidden-field promise covers field values, not this membership.

time_constraint.until is a hard cap. It applies equally to records that existed at grant issuance and to records created afterward. A continuous grant with time_constraint.until set to a past date is valid. It never discloses a record whose time_constraint.field value is at or after until. It can still disclose a qualifying record that the RS learns of after issuance, and a later full current state of a mutable_state record if its time field still qualifies. This is not an error.

For continuous grants without time_constraint.until, future records in a granted stream are included as they are collected, provided the frozen field falls within any since constraint. Stream names and fields are frozen at consent time; future stream types or fields require a new grant.

Standing authorization

Grants freeze stream names, instance handles, fields, and any time constraint at consent time. Within that resolved scope, future records are included for continuous grants. Future stream types or fields are not included; they require a new grant.

Grant narrowing

Grant narrowing (reducing the scope of an existing grant) is not supported in v0.1. Scope reduction is achieved via revoke-and-reissue: the existing grant is revoked (see Revocation) and the user issues a new, narrower grant. Authorization server UIs SHOULD model this flow as revocation followed by a new grant request.

Records from revoked grants

Revocation ends future reads, and ends processing authority as Read access and processing authority defines. Otherwise, records already delivered to the client before revocation are governed by the grant's retention policy and applicable legal obligations. PDPP does not retroactively reach into client-side data stores.

Retention

Retention is a structured policy declaration and policy commitment by the data recipient (the client). PDPP does not technically enforce retention. Enforcement is through legal agreements or contractual obligations; a trust registry supports admission and accountability for a retention commitment rather than enforcing it, because Core defines no compliance-evidence query a registry could answer. This is consistent with how OAuth 2.0 treats scope compliance: the protocol makes the commitment legible and machine-readable; external mechanisms enforce it.

{
  "max_duration": "P6M",
  "on_expiry": "delete"
}

Examples

Specific data, single use:

{
  "version": "0.1.0",
  "grant_id": "grt_001",
  "issued_at": "2026-04-06T15:00:00Z",
  "subject": { "id": "sub_x7Pd2KfL" },
  "client": { "client_id": "concert_app" },
  "source": { "kind": "connector", "id": "https://registry.pdpp.dev/connectors/spotify" },
  "source_declaration": { "version": "2026-08-11" },
  "purpose_code": "https://pdpp.dev/purpose/personalization",
  "access_mode": "single_use",
  "streams": [
    {
      "name": "top_artists",
      "instance_ids": ["inst_9fQ2xLp7"],
      "fields": ["id", "name", "genres", "popularity", "source_updated_at"],
      "time_constraint": {
        "field": "source_updated_at",
        "type": "date-time",
        "since": "2025-09-28T00:00:00Z"
      }
    }
  ]
}

Continuous access for an AI agent:

{
  "version": "0.1.0",
  "grant_id": "grt_002",
  "issued_at": "2026-04-06T15:00:00Z",
  "subject": { "id": "sub_R3mV9cYe" },
  "client": { "client_id": "personal_agent" },
  "source": { "kind": "connector", "id": "https://registry.pdpp.dev/connectors/openai" },
  "source_declaration": { "version": "2026-08-11" },
  "purpose_code": "https://pdpp.dev/purpose/agent_context",
  "access_mode": "continuous",
  "streams": [
    {
      "name": "conversations",
      "instance_ids": ["inst_Hc7vM3sD"],
      "fields": ["id", "title", "source_created_at", "source_updated_at"]
    },
    {
      "name": "messages",
      "instance_ids": ["inst_Hc7vM3sD"],
      "fields": ["id", "conversation_id", "role", "content", "source_created_at"]
    }
  ]
}

Health data with field selection and retention:

{
  "version": "0.1.0",
  "grant_id": "grt_003",
  "issued_at": "2026-04-06T15:00:00Z",
  "subject": { "id": "sub_bT6nW1qZ" },
  "client": { "client_id": "sleep_analysis" },
  "source": { "kind": "connector", "id": "https://registry.pdpp.dev/connectors/oura" },
  "source_declaration": { "version": "2026-08-11" },
  "purpose_code": "https://pdpp.dev/purpose/analytics",
  "access_mode": "single_use",
  "streams": [
    {
      "name": "sleep_sessions",
      "instance_ids": ["inst_P2xf9Lb6"],
      "fields": ["day", "total_sleep_duration", "sleep_score"],
      "time_constraint": {
        "field": "day",
        "type": "date",
        "since": "2026-01-01",
        "until": "2026-04-01"
      }
    }
  ],
  "retention": { "max_duration": "P90D", "on_expiry": "delete" }
}

8. Resource Server Interface

The resource server stores records and serves them to clients filtered by grants. A conformant resource server MUST implement this interface for cross-deployment interoperability.

Grant enforcement

On every request, the resource server:

1. Resolves the access token through authenticated RFC 7662 introspection or a local equivalent for co-located deployments. Positive introspection results MUST NOT be cached longer than min(token_exp, 60 seconds).
2. Determines pdpp_token_kind from the introspection response, then branches:
   • Client: requires an active resolved authorization context (active: true, a resolved grant). Verifies that the requested stream appears in the grant's streams list. Selects records only from the explicitly granted instance_ids and enforces the grant's time_constraint, fields, and resources constraints.
   • Owner: enforces subject, source, connection, and operation scope derived from the introspection response. Does not require or synthesize a client grant — an owner token carries none.
3. If all checks pass, returns records filtered accordingly.
4. If any check fails, returns a structured error (see Errors below).

For owner-token current-capability reads, the effective filter is the permitted owner request filter alone: an owner token carries no grant, so there is no grant filter to intersect. Request filters can only narrow the current owner read and cannot widen it.

In v0.1, client-token reads do not have request-time predicate filters (see List records below); the resource server enforces the frozen grant constraints and rejects a client request-time predicate filter rather than evaluating it. A future client-filter capability may define intersection semantics.

The RS MUST NOT re-validate authorization against the current SourceDeclaration. All enforcement constraints are in the resolved grant. Current serving metadata MAY route a granted instance, describe current schemas or query capabilities, or reject a request that cannot currently be served. It MUST NOT widen or reinterpret a stream, instance, field, time field, time type, bound, or resource key.

Token type distinction: The format of the access token is opaque to the Resource Server. The RS MUST determine the token's properties (including pdpp_token_kind) solely from the introspection response, never from token syntax.

Existing permissions and action results

PDPP grants govern the data surface named in the grant. Provider-defined permissions continue to govern actions such as posting, sending, editing, and deleting. A PDPP data grant MUST NOT authorize those actions.

For an operation using PDPP-governed data access, the RS MUST enforce the resolved grant independently of provider action permission. Existing broad read scopes MUST NOT widen that grant. Legacy interfaces MAY retain their existing permission model outside the declared PDPP surface.

When an operation needs both permissions, the server MUST verify both before execution. Denial of action permission MUST NOT cancel independently approved reads unless the authorization transaction explicitly requires both.

An action may use source-side data under its provider authorization. This does not authorize disclosure of that data to the client. An action response containing existing PDPP-governed records or facts derived from them MUST satisfy the applicable data grant.

A server MAY return a minimal action receipt under the action permission alone. Such a receipt is limited to operation status, values supplied by the caller, and a newly generated opaque operation or resource identifier. Status MUST describe only the outcome of the authorized action. The receipt MUST NOT reveal pre-existing field values, unrelated record existence, or private associations, or confer permission to retrieve source data.

If the action response would disclose unauthorized data, the server MUST redact that data or refuse the operation. The server MUST resolve a predictable disclosure failure before performing the side effect. An unexpected post-action failure MUST NOT cause broader disclosure; the provider’s action protocol governs retry and recovery.

The optional extended access profile defines owner-selected authorization, grant packages, and bounded presentation reads. These features do not add operations to the Core query interface.

Token introspection

For separated AS/RS deployments, the RS MUST authenticate to the AS introspection endpoint as required by RFC 7662. The introspection response combines standard RFC 7662 fields with PDPP-defined extensions:

The introspection response MUST contain the complete context needed to enforce the request. The separated RS MUST enforce only from that response and MUST NOT make a second AS lookup while handling the request. A co-located AS and RS MAY resolve the same context through a local equivalent.

For a client or owner token, that context includes pdpp_instance_bindings. A separated RS MUST resolve each handle only through this member and MUST fail closed when a binding is missing. A client request that needs a handle with no binding, or with a binding that names no stored instance, fails with 403 grant_invalid. For an owner token, an instance with no binding is outside the owner scope. The AS MUST NOT return pdpp_instance_bindings to a client.

Token kind extensibility: This specification defines owner and client. Deployments MAY introduce additional token kinds in companion profiles. A resource server that receives a pdpp_token_kind value it does not recognize MUST treat the token as unauthorized for all operations defined in this specification.

Positive introspection results MUST NOT be cached longer than min(token_exp, 60 seconds). Self-contained JWTs (e.g., signed JWTs) are allowed as an optimization but MUST NOT be the sole revocation mechanism; the RS MUST still be able to check active status through introspection or local equivalent.

Authentication

An AS MUST advertise https://pdpp.dev/data-access in authorization_details_types_supported in its OAuth authorization-server metadata. A client MUST establish support for this type before requesting it. Unknown detail types MUST be rejected.

Two authentication boundaries exist:

Owner operations: Authorization: Bearer <owner_token>. Core owner tokens are scoped to a single subject's data store and support the Core owner and self-export operations defined here. The RS MUST derive the subject_id from the introspection response and MUST reject any request attempting to access data outside that subject's scope. Companion profiles may define additional owner-authenticated operations. How the owner obtains this token is out of scope (device code flow, API key, or any other mechanism).

Client operations (query records, list streams, fetch blobs): Authorization: Bearer <access_token>. Access tokens are bound to a specific grant. Both token types use RFC 6750 Bearer Token format. The RS distinguishes them via pdpp_token_kind in the introspection response.

Self-export: An owner holding a valid owner token MAY query their own data using the standard client query endpoints without a client grant. This is the v0.1 self-export mechanism and does not require a separate grant. Conformant Core RS implementations SHOULD support this capability (see Section 9 conformance item 13).

Protected resource metadata

A resource server MUST publish OAuth 2.0 Protected Resource Metadata as defined in RFC 9728. RFC 9728 Section 3 fixes the document's location: the well-known URI string /.well-known/oauth-protected-resource is inserted into the resource identifier between the host component and any path or query component.

A client that reaches the resource server without a usable access token learns that location from the response itself. On a 401, the resource server MUST include a WWW-Authenticate: Bearer challenge, as RFC 6750 Section 3 requires. It MUST set error="invalid_token" when a token was presented and rejected. And it MUST include the resource_metadata parameter RFC 9728 Section 5.1 defines, carrying the URL of this document. This is the bootstrap path: without it a client holding no token has no specified way to discover where to authenticate.

The resource member is the resource server's own identifier, as RFC 9728 Section 2 requires. For a provider_native source it is the same identifier as the declaration's source.id, which is the binding Section 5 already requires an authorization server to check before consent. A resource server that serves several sources publishes one metadata document per resource identifier rather than one document listing them.

PDPP defines five additional members. The first four are REQUIRED. pdpp_freshness_granularity_seconds is REQUIRED when the resource server attaches freshness to a client-token response. RFC 9728 Section 2 permits additional parameters and RFC 9728 Section 3.2 requires a reader to ignore any parameter it does not understand, so a generic OAuth client is unaffected by their presence. Each name carries the pdpp_ prefix to keep it distinct from a future registered parameter; RFC 9728 does not itself prescribe a naming convention.

resource_name is RFC 9728's own member for a human-readable resource name, not a PDPP extension; a resource server SHOULD publish it because a consent surface has no other name to display for the resource.

RFC 9728 Section 2 makes authorization_servers OPTIONAL, and notes that in some deployments the set of authorization servers is not enumerable. A PDPP resource server MUST publish authorization_servers when that set is enumerable, so a client can reach the issuer without prior configuration. When the set is not enumerable, the resource server MUST omit the member rather than publish a partial list. The client then obtains the issuer from the grant it already holds, or from the deployment's own onboarding. Core defines no other discovery path for that case.

The capabilities member is defined by the extension profiles that advertise into it, not by Core. Core neither requires it nor constrains its contents, and a resource server that implements no extension omits it.

Endpoints

List streams

GET /v1/streams
Authorization: Bearer <access_token>

Returns streams with record counts, scoped by token kind: for a client token, the streams present in the resolved authorization context; for an owner token, the streams in the subject-scoped data store the owner token is scoped to.

Response (client token; the grant lists two instances for each stream, and the server has never collected inst_W8nt5Gq1):

{
  "object": "list",
  "data": [
    {
      "object": "stream",
      "name": "conversations",
      "record_count": 2196,
      "freshness": [
        { "instance_id": "inst_Hc7vM3sD", "last_success_at": "2026-04-06T15:00:00Z" },
        { "instance_id": "inst_W8nt5Gq1", "last_success_at": null }
      ]
    },
    {
      "object": "stream",
      "name": "messages",
      "record_count": 48302,
      "freshness": [
        { "instance_id": "inst_Hc7vM3sD", "last_success_at": "2026-04-06T15:00:00Z" },
        { "instance_id": "inst_W8nt5Gq1", "last_success_at": null }
      ]
    }
  ]
}

Get stream metadata

GET /v1/streams/{stream}
Authorization: Bearer <access_token>

A client-token caller may fetch metadata only for a stream present in its resolved authorization context. An owner-token caller may fetch metadata for streams in the subject’s data store the owner token is scoped to. Once access is authorized, the response body is actor-specific:

• Owner token: the metadata document is returned whole — full current schema, query capabilities, views, and relationships — rather than field-projected by any grant. An owner token carries no grant, so there is nothing to project against.
• Client token: the response is a closed projection derived from the resolved authorization context: only the granted stream's explicitly granted fields, and only immutable/frozen grant facts. Current query, view, relationship, filter, expansion, and aggregation capabilities MUST NOT appear unless that capability is explicitly part of a future frozen grant vocabulary. Current metadata MAY report availability or freshness (see Freshness metadata) or reject an unavailable operation, but MUST NOT make the grant appear broader or semantically different than what was issued. A source declaration change made after the grant was issued (e.g., a new field) MUST NOT become visible through this endpoint for that grant.

Owner-token response (full current metadata):

{
  "object": "stream_metadata",
  "name": "top_artists",
  "schema": { },
  "primary_key": ["id"],
  "cursor_field": "source_updated_at",
  "consent_time_field": "source_updated_at",
  "selection": {
    "fields": true,
    "resources": false
  },
  "query": {
    "range_filters": {
      "source_updated_at": ["gte", "gt", "lte", "lt"]
    },
    "expand": [
      { "name": "messages", "default_limit": 10, "max_limit": 50 }
    ]
  },
  "freshness": [
    {
      "instance_id": "inst_Zp5rT2mA",
      "last_success_at": "2026-04-06T15:01:07Z",
      "last_failure_at": "2026-04-05T09:12:40Z"
    }
  ],
  "views": [
    { "id": "basic", "label": "Artist names and genres", "fields": ["id", "name", "genres"] }
  ],
  "relationships": [
    { "name": "messages", "stream": "messages", "foreign_key": "conversation_id", "cardinality": "has_many" }
  ]
}

Client-token response (closed projection of a grant frozen to fields id, name, source_updated_at; no range filters, views, or relationships were granted):

{
  "object": "stream_metadata",
  "name": "top_artists",
  "schema": {
    "properties": {
      "id": { },
      "name": { },
      "source_updated_at": { }
    }
  },
  "primary_key": ["id"],
  "cursor_field": "source_updated_at",
  "consent_time_field": "source_updated_at",
  "selection": {
    "fields": true,
    "resources": false
  },
  "query": { },
  "freshness": [
    { "instance_id": "inst_K4wq8Rn2", "last_success_at": "2026-04-06T15:00:00Z" }
  ],
  "views": [],
  "relationships": []
}

Freshness metadata

A resource server MAY attach a freshness array to stream listings, stream metadata, and record-list responses. On /v1/streams, the array is a member of each stream item. On stream metadata and record lists, it is a top-level member of the response.

Freshness is server-observed disclosure metadata, not a grant constraint. It reports when the server last collected or confirmed data relevant to the query. It does not guarantee that the source has not changed since that time, and it does not widen or narrow access rights.

The array has one entry for each instance that the query context authorizes for the stream. For a client token, these are the instance handles that the grant lists for the stream. For an owner token, they are the instances of the stream in the owner scope. The array lists every such instance, whatever the page contains, including an instance that the server has never collected. It lists each instance once. The containing stream identifies the stream, so an entry has no stream member.

Scope. The full authorized scope of the query is the stream and the instance. For a client token, the grant's resources, time_constraint, and field projection restrict it further. Request parameters such as fields do not narrow it. An operation qualifies when it could write, change, or confirm a record visible under this scope. A check that covers the authorized data qualifies even when it finds no change. An operation confined to data outside this scope MUST NOT change the value. The value is not clipped to the record time window: a collection in September can add records dated in March. When the resource server cannot establish safely which operations are relevant to the scope, the value is null.

Success. An operation is successful when it completed and its writes were committed. A completed check that found no change is successful. Partial progress within a failed or unfinished operation is not a success. A failed operation is one that ended without success.

Null. A null value means only that the server has no reportable timestamp. It does not prove that nothing was collected or that nothing failed.

Failure timing. A client-token response MUST NOT carry last_failure_at or any other failure time. An owner-token response MAY carry last_failure_at in each entry.

Coarsening. In a client-token response, the resource server MUST truncate each last_success_at value to the granularity that it declares as pdpp_freshness_granularity_seconds in its protected resource metadata. The granularity MUST be at least 3600 seconds. The resource server truncates the value down to a multiple of that many seconds in Unix time and expresses the result in UTC. For example, a granularity of 3600 truncates each value to the start of its hour. The resource server MUST NOT report a truncated value before its interval ends. With a granularity of 3600, a success at 10:17 UTC appears as 10:00 UTC from 11:00 UTC onward. Until then, the entry reports the most recent success in an interval that has ended, or null. One granularity applies to every entry in every client-token response. Truncation keeps order: a later success never has an earlier value. A client that polls still sees each change, but only at an interval boundary. These rules limit the precision of the freshness signal. They do not guarantee timing privacy across the whole API.

Sync sessions. When it serves the first page of a changes_since session, including one that starts from beginning, the resource server takes a snapshot of the freshness array. It carries that exact snapshot through the session's page cursors and repeats it unchanged on every later page of the session.

No verdict. Core defines no staleness verdict on the wire. A client that needs one derives it from last_success_at and its own policy.

Absence of records

An empty result, the end of pagination, a tombstone, or a 404 means only that no stored record is visible under the query context. A client MUST NOT infer from these that a record does not exist at the source, or that collection is complete. This applies whatever freshness reports. The guarantees that Core makes about the client's synchronized copy of the authorized view still hold (see Incremental sync). v0.1 defines no signal that supports a claim that data does not exist at the source.

List records

GET /v1/streams/{stream}/records
Authorization: Bearer <access_token>

Returns records from a stream, filtered by the grant and any additional request parameters.

Query parameters:

The durable client-token base query surface in v0.1 is: limit, cursor, order, fields, changes_since, and blob fetch. Exact and range filter[...], expand[], and expand_limit[...] parameters are not part of the client-token surface. Owner-token current-capability reads MAY support exact and declared range filters, view, and declared expansion; those reads consult current serving metadata. Advanced stream-specific query power MUST be declared in stream metadata under query.

Unknown query parameters and unsupported query shapes MUST be rejected with HTTP 400 and MUST NOT be silently ignored.

Non-fatal warnings: A list response MAY carry a meta.warnings[] array reporting non-fatal lossiness that the server resolved without failing the request. Each entry has a stable code and a human-readable message; clients SHOULD branch on code, not on message text. A limit above the maximum is the canonical case: the RS returns the bounded page and a limit_clamped warning rather than silently dropping the excess or returning an error. Clients page forward with the returned cursor instead of expecting a larger page. Warnings are not errors and MUST NOT change the HTTP status.

Client-token requests that contain any exact or range filter[...] parameter MUST be rejected with HTTP 400 invalid_request before the RS consults current SourceDeclaration or serving metadata. This rejection applies regardless of whether the field or operator would otherwise be declared. Owner-token current-capability reads MAY accept exact filters on declared top-level scalar fields and range filters explicitly declared by current serving metadata. Unknown fields, non-scalar fields, and unsupported range shapes return HTTP 400. Owner subject, source, and connection scope are enforced independently. An owner token has no client grant field projection.

Client-token requests that contain expand[] or expand_limit[...] MUST be rejected with HTTP 400 invalid_request before the RS consults current SourceDeclaration or serving metadata. A v0.1 resolved grant does not freeze relationship identity, target stream, foreign-key join semantics, cardinality, or expansion limits. Current relationship metadata therefore cannot interpret client grant rights. Owner-token current-capability reads MAY use declared expansion against current serving metadata.

For owner-token current-capability reads, range filters (gte, gt, lte, lt) apply only to fields declared in query.range_filters. On a date or date-time field, they use the validity and comparison rules in Time constraint semantics, and an invalid value returns 400 invalid_request. Nested paths, arrays, OR grammar, and full-text search are not part of v0.1.

For owner-token current-capability reads, expansion is declaration-driven. A relation is structurally present if listed under relationships, but it is only expandable if declared under query.expand. expand_limit[{relation}] is only valid for declared has_many relations. Expansion joins only related records in the parent record's instance.

Stable sort: Records are sorted by (cursor_field, instance_id, primary_key) for cursor safety. Null or absent cursor_field values sort after present values. A changes_since session instead orders records and tombstones together by instance_id and then canonical key string, in the direction order selects. It does not follow cursor_field, which a tombstone lacks, or the order of changes, which would reveal when a hidden field changed relative to other updates.

A page cursor is bound to the query context of the first page: the grant (for an owner token, the subject and effective owner scope), stream, fields, view, expand[], expand_limit[...], order, every filter[...], and any changes_since token. A client MUST follow a next_cursor with the same context that produced it. To change the context, the client MUST restart pagination without a cursor. Resource servers MUST reject a page cursor used with a different context as invalid_cursor.

Incremental sync: Pass changes_since=beginning to start a sync, and the stored next_changes_since to retrieve the changes since a previous session. The resource server returns records within the grant's authorized field projection, and tombstones under the rules in Incremental sync. If the token has expired (HTTP 410 Gone with error code cursor_expired), the client MUST start again from beginning.

A changes_since session returns every record not visible at h0 and visible at h1 (the horizons defined in Incremental sync). For a record visible at both horizons, eligibility MUST be computed on the grant-authorized projection, not on the unprojected record. For an owner session, the projection is the session's effective fields or resolved view projection. Returning such a record when its authorized projection is unchanged is a protocol violation because it leaks that hidden fields changed.

A changes_since token is bound to the grant (for an owner token, the subject and effective owner scope) and to the query context that produced it, excluding the input changes_since value itself. For an owner session that uses view, the binding includes the resolved field set; when the view resolves to a different field set, the resource server rejects the token and the client starts a new beginning session. The resource server MUST reject a token used under another grant, subject, scope, or query context as invalid_cursor. beginning is bound only when a request uses it.

If a changes_since response is paginated, all pages in that session MUST be anchored to the same session horizon selected on the first page. New writes arriving after page 1 MUST NOT appear in later pages of that same session; they surface in the next session via the terminal-page next_changes_since. Deletion is the exception: the resource server MUST NOT serve a record on a later page if the record was deleted after page 1. The next session under a still-active grant emits its tombstone. An ordinary edit after page 1 does not override the horizon; the next session applies it. Revocation ends access and promises no later tombstone: requests fail within the propagation bound in Revocation.

Invalid owner filter: An owner-token current-capability filter on an unknown, non-scalar, or unsupported field/operator returns HTTP 400 invalid_request or unknown_field, as applicable. Client-token predicate filters are rejected earlier under the v0.1 client-filter rule.

Expansion: A client-token expansion request is rejected with 400 invalid_request before declaration lookup. For an owner-token current-capability read, requesting an undeclared relation returns 400 invalid_expand. Expansion never widens the current owner read scope.

A changes_since request with expand[] or expand_limit[...] is rejected with 400 invalid_request for every token kind. An expanded record can change when a related record changes, with no change to the parent record, so a session that compares parent versions would miss it. A client syncs each stream on its own.

Response (client token; the grant lists two instances for the stream):

{
  "object": "list",
  "url": "/v1/streams/conversations/records",
  "has_more": true,
  "next_cursor": "pc_Vx3q9LmT0bRk7ZwD2yNf5HsJa8GuPc4e",
  "freshness": [
    { "instance_id": "inst_Hc7vM3sD", "last_success_at": "2026-04-06T15:00:00Z" },
    { "instance_id": "inst_W8nt5Gq1", "last_success_at": null }
  ],
  "data": [
    {
      "object": "record",
      "id": "conv_01JQW8M2R7",
      "instance_id": "inst_Hc7vM3sD",
      "stream": "conversations",
      "data": {
        "id": "conv_01JQW8M2R7",
        "title": "Trip planning",
        "source_created_at": "2026-03-25T18:22:11Z"
      },
      "emitted_at": "2026-04-06T15:01:00Z"
    }
  ]
}

The terminal page of a changes_since request (i.e., has_more: false) MUST include next_changes_since. This terminal changes_since page for a client token has one tombstone and one changed record in the default descending key order. Its freshness array is the same on every page of the session:

{
  "object": "list",
  "url": "/v1/streams/conversations/records",
  "has_more": false,
  "next_changes_since": "cs_7Rk2VqXn9LwT4pZb0HmYc8JdF3sGa1Ue",
  "freshness": [
    { "instance_id": "inst_Hc7vM3sD", "last_success_at": "2026-04-06T15:00:00Z" },
    { "instance_id": "inst_W8nt5Gq1", "last_success_at": null }
  ],
  "data": [
    {
      "object": "record",
      "id": "conv_01JQX2P4K9",
      "instance_id": "inst_Hc7vM3sD",
      "stream": "conversations",
      "deleted": true
    },
    {
      "object": "record",
      "id": "conv_01JQW8M2R7",
      "instance_id": "inst_Hc7vM3sD",
      "stream": "conversations",
      "data": {
        "id": "conv_01JQW8M2R7",
        "title": "Trip planning, Lisbon",
        "source_created_at": "2026-03-25T18:22:11Z"
      },
      "emitted_at": "2026-04-06T15:01:00Z"
    }
  ]
}

Get a single record

GET /v1/streams/{stream}/records/{id}
Authorization: Bearer <access_token>

Returns a single record by primary key. The {id} path parameter is the percent-encoded canonical key string. Owner-token current-capability reads support expand[]; client-token requests reject it in v0.1 before declaration lookup.

The instance_id query parameter selects the record's instance. It is REQUIRED when the query context covers more than one instance of the stream. For a client token, that is when the grant lists more than one handle for the stream. For an owner token, it is when the owner scope covers more than one instance. Otherwise instance_id is OPTIONAL. The requirement depends only on the query context, not on whether two instances hold the key. The resource server MUST reject a missing required instance_id with 400 invalid_request before it looks up the record. It returns 404 not_found for an instance_id that the query context does not cover.

Delete a record (owner-authenticated)

DELETE /v1/streams/{stream}/records/{id}
Authorization: Bearer <owner_token>

Permanently removes a record from the stream. The RS may implement this as a tombstone internally. Returns 204 No Content on success. The {id} path parameter is the percent-encoded canonical key string. The instance_id query parameter follows the rule for a single-record read.

Get a blob

GET /v1/blobs/{blob_id}?instance_id={instance_id}
Authorization: Bearer <access_token>

A blob_id is unique only within one instance, and a blob request names no stream. The instance_id query parameter selects the blob's instance and is REQUIRED on every blob request. The resource server MUST reject a blob request without it with 400 invalid_request. The fetch_url that the resource server injects MUST include instance_id.

The resource server MUST NOT serve a blob unless a record that the requesting token is currently authorized to read references it. It evaluates this on each request. For a client token, it verifies that:

1. The grant lists the selected instance for a stream in which a record of that instance references this blob_id.
2. The referencing record passes all grant filters.
3. The blob_ref field is included in the grant's authorized field projection.

For an owner token authorized for blob fetch, the RS applies its subject, source, connection, and operation scope and verifies that a record of the selected instance, readable under that scope, references the blob.

A blob_id alone does not grant access. When no such record exists, the RS returns 404 blob_not_found, the same response as for an unknown or stale blob_id.

Direct response MUST include:

• Content-Type (IANA media type)
• Content-Length if known
• Cache-Control: private, no-store
• Accept-Ranges: bytes if range requests are supported

Redirect response (HTTP 302) MUST include:

• Location header pointing to a signed URL
• Cache-Control: no-store

The signed URL MUST expire no later than the positive-status cache expiry, or, if no result was cached, 60 seconds after token validation; it MUST also expire no later than the access token or grant expiration when present. The AS MUST include exp in every positive introspection response for an expiring PDPP token. A signed URL may remain usable after grant revocation until it expires; its lifetime is bounded by the preceding rule.

Redirect URLs may be valid for less than 60 seconds; clients cannot rely on the former 60-second minimum.

HEAD is supported for size checks. Range headers are recommended for large files.

Errors

Every non-2xx response returns a structured error:

{
  "error": {
    "type": "permission_error",
    "code": "grant_stream_not_allowed",
    "message": "Grant does not include stream 'messages'.",
    "param": "expand[0]",
    "request_id": "req_01JQXA3N9Y"
  }
}

Clients MUST treat unrecognized error codes as opaque and fall back to the actual HTTP status code and applicable response headers.

Authority and forward compatibility.

1. The actual HTTP status code and applicable response headers are authoritative for generic HTTP semantics, including success or failure, authentication challenges, redirection, and retry timing.
2. A recognized error.type or error.code MAY refine PDPP-specific category, presentation, or recovery behavior only when its defined semantics are compatible with the actual status code and headers.
3. An absent, unknown, malformed, or status-incompatible type or code is opaque and MUST NOT override the actual status code or relevant headers.
4. Unknown identifiers MUST NOT cause parse failure.

Clients MAY retain unknown identifiers for diagnostics, subject to local size limits, safe rendering/escaping, and privacy policy.

This makes a future error code safe to introduce: an older client keeps handling the response by status and headers, whatever the new code or type says.

Inactive tokens. An RFC 7662 response with active: false need not say why the token is inactive (RFC 7662 Section 2.2). Every inactive access token produces HTTP 401 with WWW-Authenticate: Bearer error="invalid_token". invalid_token is the Bearer challenge value (RFC 6750 Section 3.1), not a structured error code. The structured error code is authentication_error. When authenticated context establishes the cause, the structured error MAY use grant_expired or grant_revoked; those codes have HTTP status 401 and type authentication_error. A co-located RS that reads grant lifecycle state is one example of such context.

API versioning

API version is specified via header:

PDPP-Version: 2026-04-06

If the PDPP-Version header is absent, the RS uses the current stable version and returns the selected version in the PDPP-Version response header. If the requested version is not supported, the RS returns 400 unsupported_version.

Every response includes a Request-Id header for debugging.

9. Conformance

This section defines what it means to implement each PDPP role. Conformance claims should reference this section.

Conformance is role- and behavior-based. A conformant implementation is not required to use any particular vendor-hosted service, token, chain, centralized registry operator, domain, or repository deployment.

Authorization Server conformance

A conformant authorization server:

1. Accepts selection requests using the RFC 9396 authorization_details envelope with type: "https://pdpp.dev/data-access".
2. Validates selection requests against one retained SourceDeclaration snapshot: rejects unknown streams, unsupported selection parameters (e.g., time_range on a stream without consent_time_field), and unrecognized selection presets.
3. Issues grants that conform to the grant schema defined in Section 7 (normative field tables). The AS generates grant_id and issued_at; it resolves other grant fields from authenticated identities, the selection request, the accepted source declaration, eligible instance handles, user approval, AS policy, or AS-resolved client metadata.
4. Expands wildcards and selection presets into explicit stream names, fields, per-stream instance handles, resources, and frozen time constraints before issuing the grant.
5. Produces a binding-neutral Source validation failure when a request contains both or neither of streams and selection_preset. The OAuth/RAR binding maps it to RFC 9396 invalid_authorization_details.
6. MUST NOT reject a purpose_code solely because it is not in the PDPP registry. For unrecognized codes, displays purpose_description if present, or the raw URI. MAY reject a purpose_code based on local policy.
7. Renders requester identity metadata, declaration-authored data descriptions, structured policy declarations, and client-authored claims as semantically distinct categories during consent. MUST attribute client_claims to the client and MUST NOT present them as protocol-enforced terms. If client_claims are rendered during final review, binds the normalized exact claims into the immutable final approval artifact and review revision, and preserves that binding in retained consent evidence, without adding them to the resolved grant or RS enforcement. Records in the issued grant's client.client_display the exact policy_uri and tos_uri it presented during consent, and omits any it did not present.
8. Tracks grant lifecycle (active, expired, revoked). Reflects revocation immediately in introspection: the revoked grant is inactive at once, and a token is active: false when no grant it covers is active.
9. Issues access tokens bound to specific grants. Access tokens include the PDPP introspection extension fields.
10. For single_use grants, consumes the grant atomically with first client-token issuance. Gives that access token a finite expiration set by local policy and, when the grant has expires_at, no later than expires_at; that expiry ends the grant's one read window. Lets a later token in the same refresh-token family carry the grant only inside the window, reports the grant inactive for reads after it, and otherwise rejects access-token issuance against the consumed grant.
11. Validates stream/field/view/resource-id shape at grant issuance. Rejects resources on a stream with more than one instance.
12. MUST NOT define a view including fields absent from the retained SourceDeclaration schema.
13. Resolves view names to field lists at issuance time; stores resolved fields in the StreamGrant. Client-token record reads reject query-time view in v0.1. Owner-token current-capability reads MAY resolve current views.
14. Rejects a detail whose processing_permissions is malformed or contains a duplicate, unknown, or unsupported value, with invalid_authorization_details, and never ignores, substitutes, or narrows such a value or issues an ordinary grant in its place. Advertises in pdpp_processing_permissions_supported, and grants, only permissions whose complete defining contract it implements. Treats https://pdpp.dev/processing/ai_training as unsupported until the PDPP AI Training Profile is published and its registration is approved, and afterwards supports it only by conforming to that profile.
15. Resolves omitted instance IDs before the final approval surface. Binds exact resolved instances and all final decision fields to an immutable review revision or digest. Rejects stale approval if eligibility or the reviewed revision changes before approval.
16. Retains one exact SourceDeclaration snapshot through request validation, consent display, narrowing, issuance, and consent evidence. A later current declaration never substitutes for it.
17. Returns 400 unsupported_version if PDPP-Version header specifies an unsupported version.
18. For a separated AS and RS, authenticates the RS at the RFC 7662 introspection endpoint and returns the complete grant enforcement context in one response, including pdpp_instance_bindings. Never returns pdpp_instance_bindings to a client.
19. Consumes each OAuth authorization code atomically on its first successful redemption. Rejects every later redemption with invalid_grant and does not issue another token.
20. Issues a refresh token only when at least one grant the token response covers is continuous, and never extends a single_use grant's read window through refresh. It rotates refresh tokens by family. Reuse of a superseded token revokes the family and every family-linked access token, returns invalid_grant, and requires fresh authorization.
21. Rejects unsupported persisted authorization state before introspection or request handling. Does not reconstruct missing facts from current configuration and requires fresh consent when no migration applies.
22. Rejects a source declaration containing an unrecognized source.kind or streams[].semantics value.
23. Issues a grant with grantors only after each listed representative approves the same immutable final review revision. Authenticates and verifies each representative before accepting approval, binds each identity and capacity to that revision and retained consent evidence, and keeps the data subject in subject.
24. Lets the owner approve or decline each detail of a request on its own. Issues one grant for each approved, resolved detail, covering one subject, one source, and one purpose, with its own lifecycle. Identifies grants by grant_id and does not treat subject, source, and purpose as a grant key.
25. If it offers client-initiated revocation, ends grants as Section 10 defines: revoking a refresh token, current or superseded, ends every grant its family covers; revoking an access token ends its grants only when no refresh-token family covers them. In the OAuth binding, implements it as RFC 7009 token revocation and advertises revocation_endpoint in RFC 8414 metadata.
26. Ends one grant among several that share a credential without revoking that credential or ending the other grants.
27. Rejects a declaration that names an ineligible consent_time_field or a non-boolean consent_time_content_may_exceed. Rejects a time_range with no bound, a bound whose type does not match the field's format, an invalid bound, or a since not before until; the OAuth/RAR binding returns invalid_authorization_details. Never converts or rounds a bound. Sets time_constraint.type from the field's format in the retained declaration.
28. For each time-bounded stream, renders the exact bounds with their inclusive and exclusive meaning and the declared meaning of the field. Shows a relative label only when it has verified it for those bounds. Discloses that matched records can contain data from outside the bounds when the stream declares consent_time_content_may_exceed: true. For a continuous grant, discloses that the client can see records leave the window.
29. Gives each client pairwise identifiers: subject.id, grantors[].id, instance handles, and any ID Token sub differ between clients for the same subject, grantor, or instance. They stay the same for one client, are never reassigned, and cannot be reversed by a client. Sets ID Token sub to the authenticated person's identifier, which is a grantor's identifier when a representative authenticates. Uses a globally resolvable subject.id only when the owner explicitly chooses to disclose it to that client, and binds that identifier and the client into the final approval artifact and retained consent evidence. Returns an internal subject identifier and pdpp_instance_bindings only to the RS.
30. Resolves each request as Request resolution defines before final approval. Treats requested instances, resources, time bounds, and the field ceiling as upper limits, never narrows below schema-required fields, and adds nothing to compensate for a refused selection. Checks required streams and each retained stream's minimum before issuing a grant or client token. Reports an unmet minimum on a required stream as access_denied and a malformed minimum as invalid_authorization_details.
31. Resolves purpose and retention only from the current request or recipient-authorized standing terms, and retains the evidence identifying those terms with the consent evidence. Discloses during owner review that envelope identifiers are part of every disclosed record.
32. Returns one { type, grant } element per covered grant in every token response that issues a client access token, including refresh responses, as Client-visible authorization result defines. Returns the same element shape in introspection.
33. Advertises https://pdpp.dev/data-access in authorization_details_types_supported and rejects unknown detail types.
34. For a detail that carries a processing permission, requires a distinct affirmative owner selection, never preselects it, and never makes another detail depend on it. Renders each permission as a labeled term distinct from the purpose. Requires a non-empty purpose_description on an AI training detail. Issues the grant with its exact permission set or not at all, and never adds a permission to a detail that did not request it. Binds that set into final owner review, the review revision, retained consent evidence, the grant, token results, and introspection, and requires a new review when the set changes after review. Includes a reviewed expires_at in every training grant.
35. When it supports a processing permission, keeps read access and processing authority distinct as Read access and processing authority defines. Issues no further processing authority after grant revocation or grant expiry. When the grant has expires_at, issues no processing authority that outlasts it. Never lets a processing credential confer read access. Does not treat read-window closure, access-token expiry, or refresh-token replay detection alone as ending processing authority or prohibiting its renewal.
36. Its operator does not use owner data held in the AS role for AI training, except under a training grant issued to it as a client.

Resource Server conformance

A conformant Core RS:

1. Implements the query endpoints defined in Section 8: list streams, get stream metadata, list records, get a single record, get a blob, delete a record (owner-authenticated).
2. Enforces grant constraints on every client request: stream membership, explicit instance handles, frozen time_constraint, fields allowlist, and resources filter. Authorizes each disclosure under one grant and never combines the constraints of different grants.
3. In a separated deployment, resolves access tokens through authenticated RFC 7662 introspection, enforces only from that response, and makes no second AS lookup while handling the request. A co-located deployment may use a local equivalent. Caches positive results no longer than min(token_exp, 60 seconds).
4. Distinguishes owner tokens from client tokens via pdpp_token_kind.
5. For owner tokens, computes the effective filter as the permitted owner request filter alone (there is no grant filter). For client tokens in v0.1, rejects request-time predicate filters and enforces the frozen grant constraints.
6. Returns structured errors as defined in Section 8 (unified error table).
7. Supports incremental sync via changes_since on every stream, starting from beginning, with tombstone entries and HTTP 410 with error code cursor_expired on cursor expiry. Returns every record not visible at h0 and visible at h1, and omits a record visible at both horizons whose projection did not change. The projection is the grant-authorized projection for a client token, and the session's effective fields or resolved view projection for an owner token.
8. Returns next_changes_since on the terminal page of every changes_since response and on no other page.
9. Rejects client-token exact and range filter[...] parameters with 400 invalid_request before consulting current declaration metadata; owner-token current-capability reads MAY retain declared filter behavior.
10. Rejects unknown query parameters and unsupported query shapes with 400 instead of silently ignoring them.
11. Implements the PDPP-Version header negotiation.
12. Scopes owner token access to a single subject's data store; derives subject_id from introspection response. Never discloses the introspection subject_id to a client.
13. SHOULD support owner-authenticated access to the /v1/streams/{stream}/records query endpoints without a client grant, allowing the data subject to export their own data directly (self-export).
14. For owner-token stream-metadata reads, returns the full current stream metadata within the owner’s subject/source/connection scope, including current query, view, and relationship capabilities.
15. For client-token stream-metadata reads, returns only a projection derived from the resolved authorization context: the granted stream and its explicitly granted fields, and immutable/frozen grant facts. MUST NOT include current view, relationship, filter, expansion, or aggregation capability unless that capability is explicitly part of a future frozen grant vocabulary, and MUST NOT surface a source-declaration change made after grant issuance.
16. Publishes RFC 9728 protected resource metadata at the location RFC 9728 Section 3 derives from its resource identifier, carrying resource, the four required pdpp_-prefixed members defined in Section 8, and authorization_servers when its issuer set is enumerable. Also carries pdpp_freshness_granularity_seconds when it attaches freshness to client-token responses. Returns a WWW-Authenticate: Bearer challenge on 401 per RFC 6750 Section 3, carrying the RFC 9728 resource_metadata parameter.
17. Does not interpret an unrecognized stream semantic as append_only or mutable_state, or an unrecognized grant source.kind as a known provenance class.
18. Serves a blob only when a record the requesting token may currently read, including its field projection, references it. Otherwise returns 404 blob_not_found. Gives a redirect's signed URL an expiry no later than the positive-status cache expiry, or 60 seconds after token validation when no result was cached, and no later than the token or grant expiration when present.
19. Returns 401 with WWW-Authenticate: Bearer error="invalid_token" for every inactive access token. Uses the structured code grant_expired or grant_revoked only when authenticated context establishes that cause, otherwise authentication_error.
20. Emits a tombstone for each record visible at the previous horizon and not visible at the new one, and for no other record. Retains the state needed to determine visibility at every unexpired horizon, and otherwise fails the session with 410 cursor_expired. Uses the exact client tombstone shape for client tokens. For owner tokens, adds removal, and deleted_at and emitted_at only for a deletion.
21. Binds each page cursor and changes_since token to its grant, or owner subject and scope, and to its query context, and rejects a mismatch as invalid_cursor. Orders a changes_since session by instance_id and then canonical key string, does not serve a record deleted after the session's first page, and rejects expand[] and expand_limit[...] on changes_since. Issues tokens and page cursors that reveal no readable position, time, or field value, and whose equality or ordering signals no change outside the grant or owner scope.
22. Compares time values and bounds by the grant's frozen time_constraint.type, never a current declaration, as calendar dates or exact instants, without a host, viewer, or owner time zone. Validates values itself under RFC 3339, including its leap-second rule. Excludes a record whose value is absent, null, or invalid from every read surface. Applies the same rules to owner-token range filters on date and date-time fields, using the declared format.
23. Puts instance_id on every record and tombstone it serves: the grant's handle for a client token, and the owner's handle for an owner token. Serves each resource_ref in the resolved form only when the target record passes every constraint of the grant for the target stream, and otherwise in the redacted form. Identifies records within a stream by instance and canonical key in sync, removals, cursors, and single-record reads. Requires instance_id on a single-record read or record delete when the query context covers more than one instance of the stream, and on every blob fetch. Rejects a missing one with 400 invalid_request.
24. In a separated deployment, resolves every handle through pdpp_instance_bindings. Fails a client request with 403 grant_invalid when a handle the request needs has no binding or names no stored instance. Treats an owner instance without a binding as outside the owner scope.
25. When it attaches freshness, lists exactly one entry for each instance that the query context authorizes for the stream, whatever the page contains. Computes last_success_at over the full authorized scope of the query, counts only successful operations as Section 8 defines them, and reports null when it cannot establish relevance safely. In a client-token response, carries no failure time, truncates each value to its declared granularity of at least 3600 seconds, and reports no value before its interval ends. Takes a snapshot of the array on the first page of a changes_since session and repeats that exact snapshot on every later page. Reports no staleness verdict.
26. Builds disclosed data only from the top-level members the grant and the request-time field selection permit, with no nulls or fabricated values for withheld members. Refuses a read it cannot serve that way with 403 disclosure_unavailable.
27. Enforces the resolved grant independently of provider action permission, as Existing permissions and action results defines. Never treats a data grant as action permission or lets a broad read scope widen a grant, and discloses existing data in an action response only under the applicable data grant.
28. Never treats processing_permissions or a processing credential as read authority. Its operator does not use owner data it holds in the RS role for AI training, except under a training grant issued to it as a client.

Collection resource servers, connector runtimes, and connectors make no separate conformance claim in v0.1. A connector conforms to PDPP as Section 1 states: by producing a source declaration valid under Section 5 and serving its data through a resource server conforming to Section 8. The informative PDPP Collection Profile describes runtime behavior and defines no conformance requirement.

Client conformance

A conformant client:

1. Submits selection requests using the RFC 9396 authorization_details envelope.
2. Uses access tokens (not raw grants) to authenticate with the resource server.
3. Treats cursor and changes_since tokens as opaque and from distinct token spaces. MUST NOT use a next_cursor value as a changes_since parameter.
4. Stores next_changes_since from the terminal page of a changes_since response for use in the next sync session.
5. Respects HTTP 410 cursor_expired responses by starting again from beginning, rather than retrying with the expired token. After every completed beginning session, replaces its copy of the stream with that session's result.
6. Honors retention commitments declared in the grant.
7. Treats unrecognized error codes as opaque, falling back to the exact HTTP status code and applicable response headers rather than failing on an unknown code. Takes the actual status code and headers as the authoritative outcome. Uses a recognized error.type only to refine category or presentation, and only when compatible with that outcome. Ignores an absent, unrecognized, or status-incompatible type for control flow, and never fails to parse on an unknown code or type.
8. Where local policy depends on source provenance, MUST read source.kind from the issued grant and apply that policy before first use of the records. A client MUST NOT assume a provenance class it did not read from the grant, and MUST NOT treat an unrecognized source.kind as either known value. A client with no provenance-dependent policy has nothing to check.
9. Stops using an access token on a 401 with Bearer error invalid_token, and stops requests against a grant on grant_revoked. Does not treat an inactive token as proof of revocation.
10. Identifies each record within a stream by its instance_id and id together. Treats a tombstone for a record it does not hold as a no-op. Reconciles records it obtained outside sync sessions itself, because the sync guarantee covers only a copy built from sync sessions.
11. Does not infer from an empty result, the end of pagination, a tombstone, or a 404 that a record does not exist at the source or that collection is complete. Treats a null last_success_at only as the absence of a reportable timestamp.
12. Establishes that the AS advertises https://pdpp.dev/data-access before requesting it.
13. Inspects the authorization result in each token response, including refresh responses, before requesting record disclosure, and requests no disclosure when it cannot obtain or interpret the result. Does not infer authorization from its original request, a tool listing, or token syntax.
14. Does not validate a projected data object as a full stream record.
15. Trains on PDPP inputs only when every contributing PDPP input has covering training permission and valid processing authority, as AI training defines, regardless of purpose code or acquisition grant. Applies this rule to derivatives and imposes it on every recipient or subprocessor receiving PDPP inputs. Treats the legacy purpose code https://pdpp.dev/purpose/ai_training as conferring no training authority.
16. Requests a processing permission only when the AS advertises it in pdpp_processing_permissions_supported, in a detail separate from any ordinary access, and with a purpose_description where Section 6 requires one.

Conformance test suite

A formal conformance test suite is planned but is not defined in v0.1. This is out of scope for the current version.

10. Security Considerations

Declaration retrieval hygiene

An authorization server SHOULD enforce configured response-size, time, and redirect-depth limits when retrieving a declaration, and SHOULD resolve DNS freshly for each connection attempt. These limits are set by local judgment: they do not alter the declaration or grant semantics that peers must share, and a peer cannot observe which values a server chose.

Two related properties are not tuning choices and are stated in Section 5 as requirements. The safety of what a server renders is a shared invariant. So is the timing of the address check. A stale validation is what a rebinding attack exploits, so Section 5 requires the destination address be validated immediately before each connection attempt. The freshness of the DNS result above is a hygiene preference; the timing of the address check is not.

Token security

PDPP defines two token kinds at the resource server boundary: owner tokens and client tokens. Both use RFC 6750 Bearer Token format on the wire. The RS distinguishes them via pdpp_token_kind in the introspection response, not by token syntax.

For separated AS/RS deployments, the RS MUST authenticate to the AS introspection endpoint (RFC 7662) and enforce only from its response. It MUST NOT make a second AS lookup while handling the request. For co-located deployments, a local equivalent (shared database lookup or function call) is acceptable. Self-contained JWTs are allowed as an optimization but MUST NOT be the sole revocation mechanism.

Positive introspection results MUST NOT be cached longer than min(token_exp, 60 seconds). This bounds read-access revocation propagation.

An access token issued with or from a refresh-token family MUST be linked to that family and MUST have a short, token-specific expiration no later than the family or grant expiration. A token response MUST derive expires_in from the access token's persisted expiration. It MUST omit expires_in when the access token has no expiration, which Section 7 does not permit for a single_use grant. An RFC 7662 response MUST likewise omit exp when no expiration exists.

Every successful OAuth token response that contains an access token or refresh token MUST include Cache-Control: no-store and Pragma: no-cache before the response is serialized. This applies to authorization-code, refresh-token, and device-code exchanges, including package-scoped variants.

An authorization code MUST be consumed atomically on its first successful redemption. A later redemption, including one with the same valid PKCE verifier, MUST return invalid_grant and MUST NOT issue another token.

When an authorization server issues refresh tokens, each token MUST belong to a family and MUST rotate after successful use. Refresh issuance and family revocation MUST be serialized, or use equivalent atomic checks, so that a refresh cannot issue a usable token after the family is revoked. The AS MUST atomically supersede the presented token and issue one active successor. Reuse of any superseded token, including a retry after a lost successful response, MUST revoke the token family and every access token linked to that family, return invalid_grant, and require fresh authorization. Introspection MUST report every family-linked access token inactive after the replay is detected. An AS MUST NOT issue a refresh token unless at least one grant the token response covers is continuous. An access token issued from a family MAY carry a single_use grant only inside that grant's read window (Section 7); a refresh never extends the window or opens a second one. A binding in which one credential covers several grants, such as a grant package, defines how refresh covers those grants within these rules. On upgrade, an implementation MUST NOT infer family linkage for an existing bearer. Any live refresh family without persisted bearer linkage MUST be revoked together with its grant- or package-bound bearer tokens and MUST require fresh authorization. This behavior follows RFC 9700, Section 4.14.2.

Sender-constrained tokens (non-normative): Bearer tokens (RFC 6750) are the v0.1 baseline. Deployments handling sensitive standing access SHOULD consider sender-constrained tokens, which bind a token to a client-held key so that possession of the token alone is not sufficient to use it. DPoP (RFC 9449) and mutual-TLS certificate binding (RFC 8705) are both compatible with PDPP's introspection-based design. A formal optional hardening profile is a candidate for a future version.

Grant integrity

The grant is designed to be signable. The subject and client fields support future JWS/JWT signatures. Implementations MUST treat grants as tamper-sensitive. Grant signing and a formal token format are deferred to a future version; the current design is compatible with adding them without breaking changes.

Large authorization_details payloads may exceed URL length limits. Production deployments SHOULD use Pushed Authorization Requests (PAR, RFC 9126).

Credential handling

INTERACTION_RESPONSE messages in the Collection Profile may contain passwords and OTP codes. Runtimes MUST NOT log or persist credential data. See the PDPP Collection Profile for details.

Connector trust

In the Collection Profile, connectors receive credentials via the INTERACTION channel. A malicious connector could exfiltrate credentials. Production deployments SHOULD mitigate this by sandboxing connector processes (restricting network egress), using connectors from trusted registries only, or having the runtime authenticate on behalf of the connector and pass only session tokens. A formal connector trust model is deferred.

Record content and automated agents

A record's data may contain content authored by the owner, another party, or the source. That content does not itself authorize client actions. An email or message body can contain text written to steer a language model that reads it (prompt injection; see OWASP LLM01: Prompt Injection). Core does not require resource servers to detect or remove prompt-injection text from records.

A client that gives records to an automated agent SHOULD treat them as untrusted data. For example, it can keep record content separate from its instructions, and it can refuse to let record content trigger tool calls or further disclosures that the owner’s or the client’s own policy does not allow.

Trust boundary responsibilities

Revocation

The owner MAY revoke a grant at the AS by a deployment-defined means. A binding MAY also let a client revoke a credential it holds. When a client revokes a refresh token, the AS MUST end every grant that the token’s family covers, and every access token issued under those grants. Revoking a superseded refresh token of the family has the same effect. When a client revokes an access token, the AS MUST end that token. The AS MUST also end the token’s grants, but only when no refresh-token family covers them. Where client revocation is supported, disconnect therefore requires revoking the refresh-token family. Revoking an access token disconnects only when no refresh-token family covers its grants. Ending one grant among several that share a credential is a grant-level action at the AS. It MUST NOT revoke the shared credential or end the other grants.

In the OAuth binding, client-initiated revocation is RFC 7009 token revocation. Support is OPTIONAL. An AS that offers clients a way to disconnect SHOULD support it. An AS that supports it MUST advertise revocation_endpoint in its RFC 8414 metadata. RFC 7009 Section 2.1 leaves the effect on related tokens and on the grant to AS policy; the rules above fix that policy.

There is no push revocation channel in v0.1. Read-access revocation propagation is bounded by the introspection cache TTL (maximum 60 seconds), whoever starts the revocation. The AS MUST reflect revocation immediately in introspection: the revoked grant is inactive at once. A token that covers another active grant stays active; a token with no active grant is active: false. No later than 60 seconds after revocation, a request that uses the revoked grant fails. When the token is bound to no other active grant, the request fails with HTTP 401 and Bearer error invalid_token. The structured error code is grant_revoked when authenticated context establishes the cause, otherwise authentication_error (see Section 8, Errors). A binding in which one credential covers several grants defines the failure while the credential stays active.

On a 401 response with Bearer error invalid_token, the client MUST stop using that access token. On a grant_revoked error, the client MUST stop further requests against that grant. A client MUST NOT treat an inactive token as proof of revocation: the token may instead have expired or lost its refresh-token family. The HTTP status governs over an unknown error code, as Section 8 states. Companion profiles define how their active work is terminated.

Revocation ends future reads. Under a grant that carries a processing permission, it also ends processing authority over data already delivered, within the defining profile's cessation bound (Section 7). Other use of data delivered before revocation is governed by the grant's retention policy and applicable legal obligations.

Revocation is not deletion. v0.1 does not define an active erasure signal or downstream deletion callback.

11. Privacy Considerations

Data minimization

Stream-level and field-level selection implements the GDPR principle of data minimization. Clients SHOULD request only the data they need for their stated purpose. Authorization servers SHOULD display the specific fields and streams being requested during consent.

Purpose limitation

The purpose_code URI enables purpose declaration, consent display, registration policy, and implementation-defined audit or transparency mechanisms. Authorization servers MAY restrict client registrations to specific purpose codes.

Auditability and transparency boundary

PDPP core defines the authorization, grant, and disclosure semantics that make auditing and transparency possible. This includes stable identifiers and state transitions such as grant_id, client_id, subject_id, purpose_code, processing_permissions, stream and resource identifiers, timestamps, and grant lifecycle states.

PDPP core does not define a local audit-log schema, storage model, retention period for operational logs, or a user-facing disclosure-history interface. Implementations MAY maintain local records of grant issuance, disclosure, sync, token use, and revocation under local policy.

If interoperable audit or transparency events are standardized in the future, they SHOULD be defined in a separate companion profile rather than by extending the core grant or query semantics.

Retention

The retention field is a structured policy declaration and policy commitment by the data recipient. PDPP does not technically enforce retention. Enforcement is through legal agreements or contractual obligations, with a trust registry supporting admission and accountability rather than enforcement. This is an intentional design choice, consistent with how OAuth 2.0 treats scope compliance.

12. Scope and Boundaries

In scope (v0.1)

• Parameterized grants for user-owned data
• Flat relational streams with declared schemas
• Binary data references (blob_ref)
• Cross-stream references within a single subject (resource_ref)
• SourceDeclaration shared by connector-backed and provider-native sources
• Resource server query API with cursor-based pagination and grant enforcement
• Incremental sync for every stream via changes_since
• Tombstones for records that leave a client’s view
• Owner-authenticated user erasure (DELETE /v1/streams/{stream}/records/{id})
• Self-export via owner token (SHOULD-level Core RS conformance, see Section 9 item 13)
• Conformance definitions for all roles

Out of scope (v0.1)

Predicate-based grant scoping

v0.1 grants narrow access only by stream selection, named view or field projection, time range, and explicit resource identifiers. Generic predicate expressions (e.g., filter[sender_domain]=amazon.com as a grant parameter) are not supported.

Request-time filters are not grant scope. Owner-token current-capability reads MAY use filter[...] to narrow a result set, but those filters do not narrow any client grant. Client-token requests do not support request-time filters in v0.1; a client that needs a semantically bounded subset requests a named stream declared by the SourceDeclaration.

Derived subset streams (non-normative). A stream MAY represent either a source-native collection or a derived subset, provided its semantics are stable, versioned through the SourceDeclaration, and human-reviewable in consent UI. Implementations that need semantically bounded consent in v0.1 SHOULD prefer named streams with human-readable semantics (e.g., a source that exposes amazon_messages as a distinct stream) over ad hoc technical predicates. Stream names MUST NOT encode predicate logic or synthesize per-request subsets; derived streams MUST be statically declared in the SourceDeclaration.

The recommended future direction for this capability is declaration-defined parameterized subset templates with typed bound parameters and publisher-authored consent display strings.

Extensions

PDPP capabilities beyond this specification (for example, search or aggregation interfaces) are defined in companion profiles, not by extending Core semantics. Implementations MUST NOT change the meaning of Core-granted access via extensions: a grant issued under this specification authorizes exactly what Sections 6, 7, and 8 define, including any processing permission it carries, regardless of what additional capabilities a deployment offers. processing_permissions is a Core field; an extension cannot add or widen a processing permission. Optional capabilities MUST be discoverable via declared metadata rather than assumed to be present. Unrecognized declared capabilities MUST be ignorable by clients. A full capability-advertisement grammar is deliberately deferred to a future version.

Specification governance

PDPP protocol changes are proposed through public repository pull requests. In this repository, non-trivial protocol, reference contract, or architecture changes are tracked with OpenSpec before implementation so reviewers can audit the rationale, tasks, and requirement deltas.

Current active editors and maintainers are listed in MAINTAINERS.md. This repository uses a three-license split: PDPP protocol specification text (all root spec-*.md files and their mirrored site pages) is made available under the Community Specification License 1.0 (SPDX: Community-Spec-1.0; see LICENSE-specs); software packages, examples, and generated artifacts use Apache-2.0 (see LICENSE) unless a narrower file-local notice says otherwise; and user-facing documentation prose outside the specification uses CC BY 4.0 (see LICENSE-docs).

13. TypeScript Types

// --- Record model ---

interface BlobRef {
  blob_id: string;
  mime_type: string;       // IANA media type
  size_bytes: number;
  sha256: string;
  fetch_url?: string;      // Injected by resource server at read time; absent in producer output
}

interface ResourceRef {   // As a producer emits it
  source_id: string;       // SourceDeclaration source.id absolute URI
  stream: string;
  record_id: string | string[];
}

// As a resource server serves it: resolved only when the target passes every grant constraint for its stream, else redacted
type ServedResourceRef =
  | (ResourceRef & { instance_id: string })
  | { source_id: string; stream: string; redacted: true };  // No record_id or instance_id

// Served by the query API; within a stream, (instance_id, id) identifies a record
interface ResponseRecord {
  object: 'record';
  id: string;              // Canonical key string
  instance_id: string;     // Opaque instance handle; identity is (instance_id, id)
  stream: string;
  data: Record<string, unknown>;
  emitted_at: string;
}

// --- Freshness (response metadata) ---

// One entry for each instance the query context authorizes for the stream
interface FreshnessEntry {
  instance_id: string;             // Opaque instance handle, as on records
  last_success_at: string | null;  // RFC 3339; truncated to pdpp_freshness_granularity_seconds for client tokens; null = no reportable timestamp
}

type OwnerFreshnessEntry = FreshnessEntry & {
  last_failure_at?: string | null; // Owner tokens only; never in a client-token response
};

// --- Selection (request-time) ---

type TimeRange =         // At least one bound; RFC 3339 full-date or date-time matching the field's format
  | { since: string; until?: string }   // since: inclusive >=
  | { since?: string; until: string };  // until: exclusive <

// Exactly one of view or fields. fields: ["*"] requests all permitted fields.
type FieldSelection =
  | { view: string; fields?: never }
  | { fields: [string, ...string[]]; view?: never };  // Non-empty; top-level field names only in v0.1

type StreamRequest = FieldSelection & {
  name: string;
  necessity?: 'required' | 'optional';   // Default 'optional'
  minimum?: {
    fields?: string[];
    time_range?: { since: string; until: string };
  };
  instance_ids?: string[];
  time_range?: TimeRange;
  resources?: string[];    // Canonical key strings per compound key encoding
};

type PresetStreamSelection = FieldSelection & {
  name: string;
};

// --- Source binding ---

interface SourceObject {
  kind: 'connector' | 'provider_native';
  id: string;              // Stable absolute URI for the authorization and data surface
}

interface SourceRequestObject {
  id: string;              // Stable absolute URI for the authorization and data surface
  // No `kind`: the AS derives provenance from the accepted declaration
}

type SelectionRequest = {
  type: 'https://pdpp.dev/data-access';
  source: SourceRequestObject;
  purpose_code: string;
  purpose_description?: string;
  access_mode: 'single_use' | 'continuous';
  processing_permissions?: string[];  // Unique absolute URIs; closed set (Section 6); absent or empty = none
  retention?: {
    max_duration: string;
    on_expiry: 'delete' | 'anonymize';
  };
  client_claims?: { commitments?: string[] };
} & (
  | { streams: StreamRequest[]; selection_preset?: never }
  | { selection_preset: string; streams?: never }
);

// --- Grant (post-consent, immutable) ---

type TimeConstraint = TimeRange & {
  field: string;
  type: 'date' | 'date-time';  // Frozen by the AS from the retained declaration
};

interface StreamGrant {
  name: string;
  instance_ids: string[];  // Non-empty and unique; pairwise per client; a handle names one instance across the source's streams
  fields: string[];        // Non-empty and authoritative for RS enforcement
  time_constraint?: TimeConstraint;
  resources?: string[];    // Canonical key strings per compound key encoding
}

interface DataGrant {
  version: '0.1.0';
  grant_id: string;
  issued_at: string;
  subject: { id: string };  // Pairwise identifier for this client
  client: { client_id: string; client_display?: Record<string, unknown> };
  source: SourceObject;
  source_declaration: { version: string };
  purpose_code: string;    // URI
  purpose_description?: string;
  access_mode: 'single_use' | 'continuous';
  processing_permissions?: string[];  // Exact approved set; present only when non-empty; confers no read access
  streams: StreamGrant[];
  selection_preset?: string;
  retention?: {
    max_duration: string;  // ISO 8601 duration
    on_expiry: 'delete' | 'anonymize';
  };
  expires_at?: string;  // ISO 8601; required when processing_permissions includes AI training; otherwise absent means no expiry
  grantors?: Array<{ id: string; capacity: string }>;  // present only for representative approval; id is pairwise per client
  extensions?: Record<string, unknown>;  // keyed by absolute profile URI
}

// --- Source Declaration ---

interface StreamView {
  id: string;
  label: string;
  fields: string[];
}

interface StreamRelationship {
  name: string;
  stream: string;
  foreign_key: string;
  cardinality: 'has_many' | 'has_one';
}

interface StreamExpandCapability {
  name: string;
  default_limit?: number;
  max_limit?: number;
}

interface StreamQueryCapabilities {
  range_filters?: Record<string, Array<'gte' | 'gt' | 'lte' | 'lt'>>;
  expand?: StreamExpandCapability[];
  search?: {
    lexical_fields?: string[];
    semantic_fields?: string[];
  };
  aggregations?: {
    count?: true;
    count_distinct?: string[];
    group_by?: string[];
    group_by_time?: string[];
    max?: string[];
    min?: string[];
    sum?: string[];
  };
}

interface SourceDeclarationStream {
  name: string;
  description?: string;
  display?: { label?: string; detail?: string };
  semantics: 'append_only' | 'mutable_state';
  schema: Record<string, unknown>;
  primary_key: string[];
  cursor_field?: string;           // Orders ordinary list reads; changes_since uses a separate change-order position
  consent_time_field?: string;     // Top-level date or date-time field; absent means time_range not supported
  consent_time_content_may_exceed?: boolean;  // Default false; true for period or summary records
  selection: {
    // time_range capability derived from consent_time_field presence
    fields: boolean;
    resources: boolean;
  };
  views?: StreamView[];
  relationships?: StreamRelationship[];
  query?: StreamQueryCapabilities;
}

interface SourceDeclaration {
  protocol_version: '0.1.0';
  source: SourceObject;
  declaration_version: string;
  publisher: { id: string };
  display: { name: string };
  selection_presets?: Array<{
    id: string;
    label: string;
    streams: PresetStreamSelection[];
  }>;
  streams: SourceDeclarationStream[];
  extensions?: Record<string, unknown>;
}

// --- Token introspection response (PDPP extensions to RFC 7662) ---

interface PDPPIntrospectionResponse {
  active: boolean;
  pdpp_token_kind?: string;  // Core defines 'owner' and 'client'; companion profiles may add kinds (unknown kinds are unauthorized for Core operations)
  subject_id?: string;     // Enforcement identifier; may be internal; never disclosed to a client
  grant_id?: string;       // Present for client tokens
  client_id?: string;      // Present for client tokens
  exp?: number;            // Unix timestamp
  authorization_details?: Array<{ type: string; grant: DataGrant }>; // One element per authorized grant (Section 7 authorization result)
  pdpp_instance_bindings?: InstanceBinding[];  // RS-only; never returned to a client
}

interface InstanceBinding {
  source_id: string;
  stream?: string;         // Present for client tokens; absent for owner tokens
  instance_id: string;     // The grant's handle, or the owner's handle
  rs_instance: string;     // Opaque; the RS resolves it to a stored instance
}

// --- Tombstones (response objects) ---

interface ClientTombstone {
  object: 'record';
  id: string;              // Canonical key string
  instance_id: string;     // Opaque instance handle
  stream: string;
  deleted: true;
  // No data, deleted_at, or emitted_at
}

type OwnerTombstone =
  | (ClientTombstone & { removal: 'deleted'; deleted_at: string; emitted_at: string })
  | (ClientTombstone & { removal: 'left_query' });  // No deleted_at or emitted_at

Appendix A: Purpose Code Registry

Registry governance: Purpose code registries under pdpp.dev are controlled by PDPP maintainers via a public change process. Implementations MUST treat unrecognized purpose URIs as opaque identifiers and MUST NOT reject requests solely because a purpose code is unrecognized.

Purpose codes are URIs. The following codes are defined by PDPP. Implementers may define additional codes using their own URI namespaces.

A purpose code states what a use serves and never confers a processing permission. AI training is the processing permission https://pdpp.dev/processing/ai_training (Section 6), not a purpose. Earlier drafts defined the purpose code https://pdpp.dev/purpose/ai_training. It is withdrawn, is not reassigned, and confers no training authority.

Appendix B: Relationship to the Data Transfer Project (DTI)

PDPP and DTI are complementary protocols addressing different concerns. PDPP defines parameterized consent and disclosure semantics (the grant is the consent artifact; the query API is the disclosure mechanism). DTI defines canonical data models and transfer adapters (the mechanics of moving data between systems).

The two protocols can chain: a PDPP grant can authorize access to data that a DTI transfer then moves, using PDPP stream schemas to carry DTI canonical data model payloads. Formal integration between PDPP grants and DTI transfer manifests is a separate effort; no integration document is currently specified.

Note: “Data Transfer Project” is referred to as DTI (Data Transfer Initiative) in current usage, reflecting its evolution from the original DTP initiative.