Edit this page

The Policies specification defines all Ditto Protocol commands, responses, and announcements for managing Policies and their sub-resources (entries, subjects, resources, imports).

TL;DR: Policy commands use the topic pattern namespace/policyName/policies/commands/action with no channel segment. You can create, modify, retrieve, and delete Policies, entries, subjects, resources, and imports.

Topic structure for Policies

A valid topic consists of five elements:

<namespace>/<policyName>/policies/commands/<action>
  1. namespace: the namespace of the Policy.
  2. policyName: the name of the Policy.
  3. group: always policies.
  4. criterion: commands for CRUD operations, or announcements for policy announcements.
  5. action: create, modify, retrieve, or delete for commands; the announcement name for announcements.

Policy representation

The JSON representation of a Policy:

Common errors

Every Policy command can result in an error response. You correlate errors to commands via the correlation-id header.

status Description
400 Bad Format - malformed request syntax.
401 Unauthorized - missing authentication.
403 Forbidden - insufficient permissions for the operation.
404 Not Found - Policy not found for the authenticated user.
412 Precondition Failed - If-Match or If-None-Match header check failed.
413 Request Entity Too Large - Policy exceeds the size limit (default: 100 kB).
429 Too Many Requests - too many outstanding modifying requests to this Policy.

Response and Event conventions

Policy commands follow the same response and event conventions as Thing commands. See Things - Response and Event conventions for the full reference.

Key differences:

  • Policy topics have no channel segment.
  • Create/modify: 201 (created, value contains the resource) or 204 (modified, no value).
  • Retrieve: 200, value contains the requested resource.
  • Delete: 204, no value.
  • All modify and delete commands require WRITE permission on policy:/ or the targeted sub-resource.

Create and modify commands

Create a Policy

Create a Policy with the specified ID and JSON representation.

Field Value
topic <namespace>/<policyName>/policies/commands/create
path /
value Complete Policy as JSON. See Policy representation.

Response: 201 (created, value contains the Policy).

Example: Create a Policy

Create or modify a Policy

If the Policy exists, replace it. If not, create it. You need WRITE permission on policy:/. to modify an existing Policy.

Field Value
topic <namespace>/<policyName>/policies/commands/modify
path /
value Complete Policy as JSON. See Policy representation.

Response: 201 (created, value contains the Policy) or 204 (modified, no value).

Example: Modify a Policy

Modify Policy entries

Replace all entries of the Policy.

Field Value
topic <namespace>/<policyName>/policies/commands/modify
path /entries
value Policy entries as JSON. See Policy representation.

Response: 204.

Example: Modify Policy entries

Create or modify a Policy entry

Create or update a single Policy entry identified by <label>.

Field Value
topic <namespace>/<policyName>/policies/commands/modify
path /entries/<label>
value Policy entry as JSON. See Policy representation.

Response: 201 (created, value contains the resource) or 204 (modified, no value).

Example: Modify a Policy entry

Modify all subjects

Replace all subjects of a Policy entry.

Field Value
topic <namespace>/<policyName>/policies/commands/modify
path /entries/<label>/subjects
value Subjects as JSON. See Policy representation.

Response: 204.

Example: Modify subjects

Create or modify a single subject

Field Value
topic <namespace>/<policyName>/policies/commands/modify
path /entries/<label>/subjects/<subjectId>
value Subject as JSON. See Policy representation.

Response: 201 (created, value contains the resource) or 204 (modified, no value).

Example: Modify a subject

Modify all resources

Replace all resources of a Policy entry.

Field Value
topic <namespace>/<policyName>/policies/commands/modify
path /entries/<label>/resources
value Resources as JSON. See Policy representation.

Response: 204.

Example: Modify resources

Create or modify a single resource

Field Value
topic <namespace>/<policyName>/policies/commands/modify
path /entries/<label>/resources/<resource>
value Resource as JSON. See Policy representation.

Response: 201 (created, value contains the resource) or 204 (modified, no value).

Example: Modify a resource

Modify Policy entry namespaces

Modify the namespace patterns of a Policy entry.

Field Value
topic <namespace>/<policyName>/policies/commands/modify
path /entries/<label>/namespaces
value Namespace patterns as JSON array, e.g. ["com.acme", "com.acme.*"]. An empty array means the entry applies to all namespaces.

Response: 204.

Modify all Policy imports

Replace all imports of the Policy.

Field Value
topic <namespace>/<policyName>/policies/commands/modify
path /imports
value Imports as JSON. See Policy representation.

Response: 204.

Example: Modify imports

Create or modify a single Policy import

Field Value
topic <namespace>/<policyName>/policies/commands/modify
path /imports/<importedPolicyId>
value Import as JSON. See Policy representation.

Response: 201 (created, value contains the resource) or 204 (modified, no value).

Example: Modify an import

Retrieve commands

Retrieve a Policy

Field Value
topic <namespace>/<policyName>/policies/commands/retrieve
path /
fields Optional comma-separated list of fields to include.

Response: 200, value contains the Policy as JSON.

Example: Retrieve a Policy

Retrieve Policy entries

Field Value
topic <namespace>/<policyName>/policies/commands/retrieve
path /entries

Response: 200, value contains all entries as JSON.

Example: Retrieve Policy entries

Retrieve a Policy entry

Field Value
topic <namespace>/<policyName>/policies/commands/retrieve
path /entries/<label>

Response: 200, value contains the entry as JSON.

Example: Retrieve a Policy entry

Retrieve Policy subjects

Field Value
topic <namespace>/<policyName>/policies/commands/retrieve
path /entries/<label>/subjects

Response: 200 with subjects as JSON.

Example: Retrieve subjects

Retrieve a Policy subject

Field Value
topic <namespace>/<policyName>/policies/commands/retrieve
path /entries/<label>/subjects/<subjectId>

Response: 200, value contains the subject as JSON.

Example: Retrieve a subject

Retrieve Policy resources

Field Value
topic <namespace>/<policyName>/policies/commands/retrieve
path /entries/<label>/resources

Response: 200 with resources as JSON.

Example: Retrieve resources

Retrieve a single Policy resource

Field Value
topic <namespace>/<policyName>/policies/commands/retrieve
path /entries/<label>/resources/<resource>

Response: 200, value contains the resource as JSON.

Example: Retrieve a resource

Retrieve Policy entry namespaces

Retrieve the namespace patterns of a Policy entry.

Field Value
topic <namespace>/<policyName>/policies/commands/retrieve
path /entries/<label>/namespaces

Response: 200, value contains the namespace patterns as JSON array, e.g. ["com.acme", "com.acme.*"]. An empty array means the entry applies to all namespaces.

Retrieve Policy imports

Field Value
topic <namespace>/<policyName>/policies/commands/retrieve
path /imports

Response: 200, value contains all imports as JSON.

Example: Retrieve imports

Retrieve a single Policy import

Field Value
topic <namespace>/<policyName>/policies/commands/retrieve
path /imports/<importedPolicyId>

Response: 200, value contains the import as JSON.

Example: Retrieve an import

Delete commands

All delete responses return status 204 on success.

Delete a Policy

Field Value
topic <namespace>/<policyName>/policies/commands/delete
path /

Example: Delete a Policy

Delete a Policy entry

Field Value
topic <namespace>/<policyName>/policies/commands/delete
path /entries/<label>

Example: Delete a Policy entry

Delete a single subject

Field Value
topic <namespace>/<policyName>/policies/commands/delete
path /entries/<label>/subjects/<subjectId>

Example: Delete a subject

Delete a single resource

Field Value
topic <namespace>/<policyName>/policies/commands/delete
path /entries/<label>/resources/<resource>

Example: Delete a resource

Delete a single Policy import

Field Value
topic <namespace>/<policyName>/policies/commands/delete
path /imports/<importedPolicyId>

Example: Delete an import

Announcements

Policy announcements use the announcements criterion in the topic:

<namespace>/<policyName>/policies/announcements/<announcement-name>

The Ditto Protocol representation:

SubjectDeletionAnnouncement

Ditto publishes this announcement when subjects of a Policy are deleted or about to be deleted.

Field Value
topic <namespace>/<policyName>/policies/announcements/subjectDeletion
path /
value JSON object with deleteAt (ISO-8601 timestamp) and subjectIds (JSON array of subject strings).

Example: Subject deletion announcement

Further reading

Tags: protocol